search

TOMP-WG / TOMP-API

Transport Operator to Mobility-as-a-Service Provider-API development for Mobility as a Service
Apache License 2.0
100 stars 41 forks source link

The API does not follow RESTful standards #54

Closed paxx-dev closed 5 years ago

paxx-dev commented 5 years ago

(more details will follow later)

To make our API more RESTful, it should conform to the following requirements:

  1. Requests should be made on objects, nouns, not as process flow, verbs. We do this to some extend, but not everywhere, specifically not for anything that isn't a top-level object (booking, trip) Example: DELETE /bookings/cancel-request/{id} -> DELETE /bookings/{id} or POST /bookings/{id}/cancellation
  2. Standard HTTP verbs should be used to convey the kind of action requested. We largely do this already, but there often is duplication of the meaning of the HTTP verb in to URL Example: POST /bookings/availability-request -> POST /bookings/
  3. Possible actions and related objects should be communicated in the responses to requests. Example: After POSTing a new booking, not only should the location and content of the booking be returned, but also the URIs at which it can be modified, associated assets, etc.

For now I'd like to focus on consistency on points 1 and 2.

eborremans commented 5 years ago

I am not a REST API expert, but some research lately shows me that most of the articles on RESTFullness use examples of relatively simple object hierarchies and resource repositories. A very common example for instance is 'products'. Most of the HTTP protocol can be relatively easily explained for such an examples (which basically is CRUD on resources). In that respect, it shouldn't be too hard in our context to apply these principles to assets, pricing, invoices, etc. However, at least to me, for objects involved in complex state transitions (like bookings and trips), it is not always directly obvious how to apply the RESTful practices to them, especially when a service call starts a more or less complex process that changes the state of a resource.

Another topic that relates to this is the various REST API building specifications that are available such as JSON:API (https://jsonapi.org/). Specifications like these, among others, help formalize and standardize the json format of your API, which can be extremely helpful when representing and navigating data in client applications.

I am just saying that we should keep this in mind when deciding how to ensure our APIs follow these RESTFullness guidelines.

edwinvandenbelt commented 5 years ago

Hmmm. At first look the JSON:API looks pretty strict... POST for insert, GET for retrieving, PATCH for update and DELETE for removal. The main problem i've got, is that we send a lot of data (at least for the availability-check). It would create a very long URL to contain all the conditions using a GET (GET doesn't allow a request body).

The format is fine to me, although I don't see the added value.

pimmeh commented 5 years ago

Is this issue import to 'fix' for version 1.1 of our API? It does sound like it.

Tjalle commented 5 years ago

In order to stay within restfull standards and because of earlier issues with long query strings, I always use POST results for things as matching requests with a lot of data. It can be interpreted as : I post a new question to your service and stays within the guidelines.

Having very large GET calls can lead to unexpected issues, with request content that will be cut of at a certain point. Because some browsers have a maximum string length for querystrings - (mainly IE of course). It's also not recommended because of the speed ( slow HTTP request errors and such).

For update of a full entity PUT is recommended, PATCH is used to update parts of an entity.