Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add how to define new endpoints in web for api-versioning.md #50743

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Add how to define new endpoints in web for api-versioning.md #50743

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
80695aa
Add how to define new endpoints in web for api-versioning.md
kimlisa Jan 3, 2025
ea43ebe
Address review
kimlisa Jan 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 32 additions & 1 deletion rfd/0179-api-versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,37 @@ func (h *Handler) getFoos() (interface{}, error) {
}
```

#### Defining new endpoints in the web client
All endpoints should be defined in a JS object, similary done [here](https://github.com/gravitational/teleport.e/blob/ebf079267020d59f14353dd3495b4fd783339fa5/web/teleport/src/config.ts#L134).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
All endpoints should be defined in a JS object, similary done [here](https://github.com/gravitational/teleport.e/blob/ebf079267020d59f14353dd3495b4fd783339fa5/web/teleport/src/config.ts#L134).
All endpoints should be defined in their own objects inside the `cfg.api` object in appropriate project's `config.ts` file, like in [this example](https://github.com/gravitational/teleport.e/blob/ebf079267020d59f14353dd3495b4fd783339fa5/web/teleport/src/config.ts#L134).


This helps us tell apart same paths but with different HTTP verbs.

Example of a new single endpoint:

```ts
user: {
create: '/v1/webapi/users',
}
```

Example of an endpoint with same paths but with different verbs:

```ts
user: {
create: '/v1/webapi/users',
update: '/v1/webapi/users',
}
```

Example of creating a version N endpoint:
```ts
user: {
// TODO(<your-github-handle>): DELETE IN 18.0 - replaced by /v2/webapi/users
create: '/v1/webapi/users',
createV2: '/v2/webapi/users',
}
Comment on lines +192 to +195
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we'd only need the verbV2 if we plan on using both (like a fallback for example). Otherwise, the current client should just have the version it plans on using.

So I think this specific pattern is fine, I just don't think we'll be using it too often

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

got it, i think you wanted me to leave some comment about marking it for deletion only if we need a fallback right? which i did here: https://github.com/gravitational/teleport/pull/50743/files#diff-7852f06643f466fb42c702c6f8bb51f67339dbb53e40629bce1c2a69918d1d0dR188

```

### Removing an endpoint
An endpoint can be removed in a major version n+2, where n is the last major
version where the endpoint was used.
Expand Down Expand Up @@ -269,4 +300,4 @@ tab was available in clients that _may_ have been communicating with proxies
older than the required version. So a check was made to see if that proxy
supported pinned resources, and if it wasn't, made the error known to the user
that "Pinned Resources is supported by proxies version 14.1+" (or something like
that).
that).
Loading