search

KA-Huis / space-management

The core application of the KA-Huis
https://ka-huis.github.io/space-management
Apache License 2.0
0 stars 0 forks source link

REST API versioning #66

Closed cyrildewit closed 2 years ago

cyrildewit commented 2 years ago

Objective

Versioning our REST API is mandatory to provide backwards compatibility to previous API designs. Instead of maintaining old behaviour, versioning allows us to independently work on the REST API without breaking old integrations. There are multiple options to versioning our API. This ticket is about researching available options and collecting the pros and cons of these. Then we can discuss these options with the team and pick one.

Analysis

Most APIs that are publicly available are usually versioned to provide backwards compatibility when breaking changes to the design are introduced.

What is a breaking change?

"Any change to your API contract that forces the consumer to also make a change".

  • "Tim KLeier"

API change management

From blog post "How to Version a REST API" by Tim Kleier.

Rules for extending

  1. You MUST NOT take anything away
  2. You MUST NOT change processing rules
  3. You MUST NOT make optional things required
  4. Anything you add MUST be optional

From blog post "API Change Management" by Zdenek "Z" Nemec.

Breaking change

1.Resource Identifier (URI) including any query parameters and their semantics

  1. Resource metadata (e.g. HTTP headers)
  2. Resource data (e.g. the HTTP body) fields and their semantics
  3. Actions the resource affords (e.g., available HTTP Methods)
  4. Relations with other resources (e.g., Links)

From blog post "API Change Management" by Zdenek "Z" Nemec.

Types of API Versioning

URI path

http://example.com/api/v1/products
http://api.example.com/v1/products

Query params

http://www.example.com/api/products?version=1

Header

Accept: version=1.0

Deprecating

Deprecating old variants of the API should be done carefully. The variant should first of all be listed as deprecated in the API documentation. The documentation can be eventually removed in newer versions, while still keeping the API in place.

Available PHP tools

Versioning schemes

Semantic Versioning (SemVer) is the most commonly used scheme and a good option.

See Semantic Versioning 2.0.0.

Advice

The REST API will be versioned with SemVer. Since only major versions are allowed to contain breaking changes, we only have to make the major version configurable when consumers are making requests to the API. The strategies explored in the analysis chapter can be applied.

The PHP tools are useful for not necessary to versioning our API. Once these tools becomes needed, they can be discussed with the team.

As we've seen in the analysis, there are multiple options to let clients decide which version of the API they want to use. Since using the query string method always requires the version to be added to the request body it can overlap with the endpoint design and make debugging a little bit harder. My preference goes to either the header or URI path method. Clients can configure a default header or define one base URI with the requested version.

Let's first discuss the URI path method. This method is easier and more straight-forwarded to implement, since we can define groups of routes for each API version. For example: example.com/api/v2/users will simply be defined and pointed to the UserController@index action within the V2 namespace. Using the header method will require a more complex solution to apply the expected version logic. Since the routes will possibly stay the same, the different flow should be catched and handled.

I would advice to go with the URI path method, since it will not require a lot of unnecessary complex solutions for now.

Design

Route scheme

Proposed structure: {baseUri}/api/{apiVersion}

Classes and namespaces

A new API directory will be created within the App namespace. Each major API version will be build within this directory under a version namespace like V1 or V2.

These version directories will contain the related controllers, resources, form requests, etc.

Resources

cyrildewit commented 2 years ago

@Hoopless I finished this little analysis and advice. Do you have any feedback or comments. The advice part is the most important thing from this ticket.

JSTLWK commented 2 years ago

We have discussed this both in a meeting, the meeting video can be found in the general chat. We have concluded that the advice you give is what we both want in URL structure and folder structure.

cyrildewit commented 2 years ago

@Hoopless and I discussed this ticket using practical examples. By grouping the related code on a higher level (App/APi/V1), everything that is not related to this scope is automatically filtered out.