Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Apidays Paris 2023 - Real-Life REST API Version...

apidays
December 14, 2023

Apidays Paris 2023 - Real-Life REST API Versioning, Alexandre Touret, Worldline

Apidays Paris 2023 - Software and APIs for Smart, Sustainable and Sovereign Societies
December 6, 7 & 8, 2023

Real-Life REST API Versioning: Strategies and Best Practices
Alexandre Touret, Software Architect at Worldline

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/

apidays

December 14, 2023
Tweet

More Decks by apidays

Other Decks in Programming

Transcript

  1. • Do I really need to version this API? •

    How to handle versioning? • How many versions can I handle at the same time? • Is my platform compatible with? • What are the impacts on my configuration? • What about security & authorization mechanisms? Some questions to ask to yourself
  2. ✓ adding an operation ✓ adding an optional parameter ✓

    adding an optional request header ✓ adding a response field ✓ adding a response header ✓ adding enum values ✓ removing an entire operation ✓ removing or renaming a parameter ✓ removing or renaming a response field ✓ adding a new required parameter ✓ making a previously optional parameter required ✓ changing the type of a parameter or response field ✓ removing enum values ✓ adding a new validation rule to an existing parameter ✓ changing authentication or authorization requirements Changes according GitHub https://docs.github.com/en/rest/overview/api-versions?apiVersion=2022-11-28 Breaking Non-breaking
  3. A breaking change in the API contract e.g.,: In the

    Book object, the author field moves to a list of authors So what ? What is a breaking change?
  4. How to handle versioning? URL Exemple /v1/api/books HTTP Header Exemple

    X-API-VERSION : v1 Content-Type Exemple Accept: application/vnd.myn ame.v1+json RFC 9110
  5. URL specification versioning Versions evolve through breaking changes URL specification

    versioning It sticks to the V1 Header specification versioning "X-GitHub-Api-Version” What about GAFAM & co?
  6. If you want to use URL Versioning → put the

    version in the URI If you want to postpone it /v1/api/books
  7. • Adapt the code source to deliver at the same

    time many versions Source code management • JAR, ZIP, Helm charts, Docker images One deliverable per branch/tag • Dynamic: Configuration server • Static: Config Maps Configuration • Databases Scripts Impacts
  8. • Pinpoint who uses your API • Publish and use

    dashboards (e.g., Kibana) • Use an API-KEY to clearly identify your customers Observability → Define the best strategy → Better anticipate the decomissioning of your deprecated APIs
  9. • The API Gateway exposes both the two versions (V1

    & V2) • It transforms requests and responses from the V1 to V2 format If we only deploy the latest service?
  10. ├── │ └── touret │ └── │ └── │ ├──

    │ │ ├── 1 │ │ ├── 2 │ │ ├── dto │ │ ├── y │ │ ├── │ │ ├── │ │ ├── y │ │ └── Handle versioning in the code base 1 version = 1 package Let the application deal w/ version handling ├── │ └── touret │ └── 1 │ └── 2
  11. • Share your strategy to all the stakeholders • Draft

    your roadmap and changelogs on a regular basis • Use HTTP responses headers to indicate your API is deprecated Communication Deprecation: version="v1" Link:https://developer.example.com/deprecation
  12. Authorization policy V1 Bookstore admin Bookstore customer Users Roles Permissions

    Books/write Books/search Isbns/read Isbns/write Books/read Admin Search Read
  13. A new policy (V2) Bookstore Admin Bookstore customer Users Roles

    Permissions Books/search Isbns/read Books/write Isbns/write Books/read Authors/write Authors management admin
  14. For your next APIs Avoid it first Identify breaking changes

    Work on the modularity Observe! Consider the big picture Communicate!
  15. D ’ ! Follow & get in touch @touret_alex linkedin.com/in/atouret

    blog.worldline.tech @WorldlineTech Follow our tech team: Follow me: blog.touret.info alexandre-touret Feedback