Clarify different between API Gateway and Gateway API #2191

david-martin · 2023-07-17T11:04:36Z

What type of PR is this?

/kind documentation

What this PR does / why we need it:

Clarify potential terminology confusion around Gateway API & API Gateway

Which issue(s) this PR fixes:

Fixes #1157

Does this PR introduce a user-facing change?:

Yes.

Clarify wording on website around Gateway API vs API Gateway

k8s-ci-robot · 2023-07-17T11:04:44Z

Welcome @david-martin!

It looks like this is your first PR to kubernetes-sigs/gateway-api 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/gateway-api has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2023-07-17T11:04:45Z

Hi @david-martin. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

gyohuangxin

@david-martin Thanks for your PR, I leave some my thoughts for your reference.

site-src/index.md

gyohuangxin · 2023-07-20T08:46:19Z

site-src/index.md

+
+Gateway API is an interface, or set of resources, that model service networking
+in Kubernetes. One of the main resources is a `Gateway`. If you implement
+Gateway API, you are a Gateway provider. A `Gateway` resource declares the


I think it's a little bit confusing to say "If you implement Gateway API, you are a Gateway provider", how about "As a Gateway Provider, you can implement the Gateway API to model Kubernetes service networking in an expressive, extensible, and role-oriented way." ?

Thanks.
All great suggestions, which have now been incorporated

gyohuangxin · 2023-07-20T08:55:27Z

/ok-to-test

gyohuangxin

Another nit, otherwise lgtm.

site-src/index.md

gyohuangxin · 2023-07-20T09:12:22Z

@robscott Could you please give your words on this?

arkodg · 2023-07-20T17:45:41Z

site-src/index.md

+The concept of a Gateway is a networking component that allows data to transfer from one
+network to another network.
+
+An API Gateway is a Gateway implementation that deals more specifically with backend services


imo this doesnt quite feel right.
I asked ChatGPT what an API Gateway was and here is its answer

a suggestion would be to consider reframing this as API Gateway is a Gateway implementation that deals with Request Routing, Security and many more things like Caching, Monitoring, Transformations where as Gateway API is an interface focused on defining standards for networking and security settings associated with Ingress and the Mesh

I see what you're getting at, focusing on the features.

My intention here was to distinguish between a gateway (abstract networking thing) and an API gateway (networking thing that exposes backend services via APIs).
My preference was for less detail, and let the reader do their own research on what are the detailed features an API Gateway might provide are.

If you'd like to suggest any changes though via the github suggestion feature, that would allow others to chime in more easily too.

site-src/index.md

robscott

Thanks @david-martin! This has been such a common question, I'm glad you're taking the time to answer it in our docs.

site-src/index.md

david-martin · 2023-07-25T10:21:22Z

Pushed up changes with latest round of feedback.

The question What's the difference between Gateway API and an API Gateway now shows up on the index page and faq page.
The other question about API Mgt has been moved to the faq page.

Removed duplicate wording, reordered the answer paragraphs to main question & wrapped at 80 characters.

edit fixed up some formatting issues on the faq page as well

arkodg · 2023-07-25T17:00:25Z

site-src/faq.md

+  Gateway type (or class) to instantiate and its configuration. As a Gateway
+  Provider, you can implement the Gateway API to model Kubernetes service
+  networking in an expressive, extensible, and role-oriented way.
+  Most Gateway API implementations are API Gateways to some extent, but not all


Suggested change

Most Gateway API implementations are API Gateways to some extent, but not all

Most Gateway API implementations are subsets of API Gateways, but not all

I actually personally prefer "to some extent" here as it leaves more flexibility and allows for full API Gateways to also implement Gateway API. I think it's possible that fully featured API Gateways would implement Gateway API + provide configuration through other means to provide full API Gateway functionality.

robscott · 2023-07-25T17:56:20Z

Thanks @david-martin! Will leave final LGTM for someone else.

/approve

k8s-ci-robot · 2023-07-25T17:56:28Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: david-martin, robscott

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~site-src/OWNERS~~ [robscott]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

youngnick · 2023-07-26T05:48:22Z

site-src/faq.md

+  capabilities of a backend service, while providing extra capabilities for
+  traffic routing and manipulation, such as load balancing, request and response
+  transformation, and sometimes more advanced features like authentication and
+  authorization, rate limiting, and circuit breaking.


Tiny nit: One extra newline here will ensure these paragraphs are separated in the rendered text, which will make this easier to read.

I played around with this, having the extra newline as you suggest.
However, when viewing the preview in netlify I noticed odd formatting.
Here's a screenshot with newlines

and without

hence why I went without.
I'm not sure how best to resolve this, without maybe dropping to raw html?

Sorted.
Looks like the indentation was off on a number of blocks.

youngnick

Basically LGTM, just one small formatting nit and then I'll do the honours.

Thanks for this @david-martin, this is great work.

david-martin · 2023-07-27T08:36:33Z

just one small formatting nit and then I'll do the honours.

@youngnick Good to go here

youngnick · 2023-07-27T12:52:50Z

/lgtm

k8s-ci-robot added release-note Denotes a PR that will be considered when it comes time to generate release notes. kind/documentation Categorizes issue or PR as related to documentation. labels Jul 17, 2023

k8s-ci-robot requested review from bowei and keithmattix July 17, 2023 11:04

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Jul 17, 2023

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Jul 17, 2023

k8s-ci-robot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Jul 17, 2023

david-martin force-pushed the api-gateway-wording branch from 699414a to aa38d66 Compare July 17, 2023 13:15

david-martin mentioned this pull request Jul 20, 2023

Improvement to the website description of what a Gateway API is and is not #1157

Closed

gyohuangxin reviewed Jul 20, 2023

View reviewed changes

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Jul 20, 2023

david-martin force-pushed the api-gateway-wording branch from bf08257 to dcaf850 Compare July 20, 2023 09:00

gyohuangxin reviewed Jul 20, 2023

View reviewed changes

site-src/index.md Outdated Show resolved Hide resolved

david-martin force-pushed the api-gateway-wording branch from dcaf850 to bb17242 Compare July 20, 2023 09:25

arkodg reviewed Jul 20, 2023

View reviewed changes

youngnick reviewed Jul 24, 2023

View reviewed changes

site-src/index.md Outdated Show resolved Hide resolved

robscott reviewed Jul 24, 2023

View reviewed changes

site-src/index.md Outdated Show resolved Hide resolved

site-src/index.md Outdated Show resolved Hide resolved

site-src/index.md Outdated Show resolved Hide resolved

site-src/index.md Outdated Show resolved Hide resolved

site-src/index.md Outdated Show resolved Hide resolved

david-martin force-pushed the api-gateway-wording branch from cff4796 to f2278eb Compare July 25, 2023 10:18

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Jul 25, 2023

david-martin force-pushed the api-gateway-wording branch 2 times, most recently from c6ee580 to ac44575 Compare July 25, 2023 10:25

shaneutt mentioned this pull request Jul 25, 2023

Conformance Profiles: summaries for profiles without content #2235

Closed

arkodg reviewed Jul 25, 2023

View reviewed changes

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jul 25, 2023

youngnick reviewed Jul 26, 2023

View reviewed changes

david-martin added 2 commits July 27, 2023 09:33

Clarify different between API Gateway and Gateway API

b887052

Fix FAQ formatting

8296590

david-martin force-pushed the api-gateway-wording branch from 7e13e47 to 8296590 Compare July 27, 2023 08:33

k8s-ci-robot assigned youngnick Jul 27, 2023

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 27, 2023

k8s-ci-robot merged commit 5eaacdc into kubernetes-sigs:main Jul 27, 2023

	Most Gateway API implementations are API Gateways to some extent, but not all
	Most Gateway API implementations are subsets of API Gateways, but not all

Clarify different between API Gateway and Gateway API #2191

Clarify different between API Gateway and Gateway API #2191

Uh oh!

Conversation

david-martin commented Jul 17, 2023

Uh oh!

k8s-ci-robot commented Jul 17, 2023

Uh oh!

k8s-ci-robot commented Jul 17, 2023

Uh oh!

gyohuangxin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gyohuangxin commented Jul 20, 2023

Uh oh!

gyohuangxin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gyohuangxin commented Jul 20, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

robscott left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

david-martin commented Jul 25, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robscott commented Jul 25, 2023

Uh oh!

k8s-ci-robot commented Jul 25, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

youngnick left a comment

Choose a reason for hiding this comment

Uh oh!

david-martin commented Jul 27, 2023

Uh oh!

youngnick commented Jul 27, 2023

Uh oh!

Uh oh!

david-martin commented Jul 25, 2023 •

edited

Loading