Repository navigation
Docs to migrate REST APIs to Twirp - #347
Merged
Merged
Conversation
marioizquierdo
commented
Jan 21, 2022
| 1. `cd website` | ||
| 2. `npm install` | ||
| 3. `npm start` | ||
| 4. Navigate to http://localhost:3000/twirp. |
Contributor
Author
There was a problem hiding this comment.
This is the only part I updated in this document. The way to install docusaurus changed a little bit and the docs no longer apply. Everything else was prettify in my editor "fixing" the markdown
wmatveyenko
suggested changes
Jan 25, 2022
|
|
||
| Migrating existing REST/JSON APIs to Twirp is a case-by-case scenario. Unfortunately, it involves creating a new service, generating a new client, and migrating callers to use the new endpoints in the new client. | ||
|
|
||
| Twirp APIs are restricted to requests in the form `POST [<prefix>]/[<package>.]<Service>/<Method>` (see [Routing and Serialization](routing.md)). That limitation is what allows to build simple and consistent API schemas, but it also means that each REST API endpoint will have a different way to be translated into a Twirp endpoint. Most REST/JSON APIs don't have strongly defined schemas, and tend to have quirks and edge cases that are hard to automate. |
Contributor
There was a problem hiding this comment.
Change "what allows to build" to "what allows building"
| 2. Write a Protobuf schema with the same endpoints. Remember that Twirp endpoints depend on the Protobuf message used as request, but can also read [HTTP headers](headers.md) if needed. Respect Protobuf [naming and best practices](best_practices.md) when possible, but don't try and significantly change the API design of your application during the migration, it will be a lot easier to migrate callers to the new API if the new endpoints closely resemble the old endpoints. Try to use parameter types that are similar to the older parameters. Use comments on the schema to clarify edge cases. | ||
| 3. If the API is too big, it may be better to only migrate a few endpoints first. Twirp APIs are good at evolving over time, you can always add more endpoints later. | ||
| 4. Generate code and implement your new API methods. You may be able to re-use some of the older code from the previous endpoints. One way to do this is to implement the new service in a subfolder inside the same project, and then mount the new Twirp handler in a sub-route (you can use the default `/twirp` prefix, or specify a different prefix path if needed). | ||
| 5. Make sure to track stats about API endpoint usage, so you can see the traffic being migrated to the new endpoints. Using [hooks or interceptors](hooks.md), or HTTP [middleware](mux.md) can be useful. |
Contributor
There was a problem hiding this comment.
remove comma in "), or HTTP"
| 3. If the API is too big, it may be better to only migrate a few endpoints first. Twirp APIs are good at evolving over time, you can always add more endpoints later. | ||
| 4. Generate code and implement your new API methods. You may be able to re-use some of the older code from the previous endpoints. One way to do this is to implement the new service in a subfolder inside the same project, and then mount the new Twirp handler in a sub-route (you can use the default `/twirp` prefix, or specify a different prefix path if needed). | ||
| 5. Make sure to track stats about API endpoint usage, so you can see the traffic being migrated to the new endpoints. Using [hooks or interceptors](hooks.md), or HTTP [middleware](mux.md) can be useful. | ||
| 6. The API callers (upstream services) need to import the new Twirp client and update their calls to use the new Twirp API. Here is where making the new API similar to the old one will be the most useful. Some services may be able to just replace the old client with the new one and start sending traffic to the new endpoints. If they have a decent staging/canary environment and a good deploy system that allows for quick rollbacks, that could be enough to test that the new API is handling the new traffic properly. In other cases, you will need to implement a slider to migrate traffic slowly (10%, 50%, 100%). The slider can be implemented in different ways, either with if statements, e.g. `if r.Intn(100) < 10 { callNewClient() } else { callOldClient() }`, or in more complex cases, with a custom client that implements the same Twirp service interface, but it is able to split the traffic between the old API and the new API. |
Contributor
There was a problem hiding this comment.
Change "Here is where making the new API similar to the old one will be the most useful." to "This is why making the new API similar to the old one is useful."
Contributor
Author
|
@wmatveyenko thanks for the review. I addressed the docs with the suggestions, and took the chance to give it another edit pass. |
wmatveyenko
approved these changes
Feb 7, 2022
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Even though the migration process is a case-by-case scenario, it is still useful to have some basic guidelines for the recommended approach. If the community has useful tools that could be used in some cases, we could add links to those tools in this page too. If there are other guides for migrating from gRPC, Swagger and others, we could add those sections on this document later too.
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.