RESTful Service Guide

We had some inconsistencys and open questions related to RESTful API design, which lead to ugly request URLs. This is why we define some basic guidelines here. The interested reader may continue his studies in this paper where some of these information were extracted from, and this book referenced from the paper.

Criteria

Criteria 1-12 are highly relevant while criteria 13-17 are related, but not highly relevant.

1. Availability of Formal Description. We use Swagger for documenting APIs. However, our JAX-RS support is limited, so this can be improved.
2. Links in Representations. Links to other resources are navigational help and provide follow-up actions. It allows a loose coupling between client and API since the client gets an URL where he can proceed. However, this is not possible in las2peer (yet?) since the service never knows the used endpoint (WebConnector) where he actually runs, so a service can only provide a relative link.
3. Encode IDs in URIs.
4. Number of Resource Types.
5. Versioned service endpoint. las2peer has a versioned service endpoint to choose different service versions. This is common practise to keep multiple APIs running at the same time and to not break compatibility. However, this violates the principle of resource addressability.
6. Scoping Information. Resource information should be encoded in resource URIs.
7. Parameter Sources. Parameters should be passed in the POST/PUT body to support richer semantics. Only filters are passed as GET parameter (e.g. /list?orderBy=...).
8. Meaningful HTTP Status Codes. Enhance error handling by sending reasonable HTTP status codes.
9. HTTP Methods Used. Using just a single method can also point to an overloading of functionality.
10. HTTP Method Override. Some browsers only accept only GET and POST.
11. Representation Formats. Commonly used formats are XML, JSON, serialized PHP, ATOM, HTML and CSV
12. Representation Format Selection. HTTP allows the user to specify the media type. Most common way is to pass the format as an argument.
13. User Authentication. HTTP provides a general mechanism, including specific authentication protocols to be used. Other standards such as the OAuth protocol have emerged.
14. Secure Connections. Support SSL-secured connections.
15. Accessibility via other protocols.
16. Type of Registration Required. Provide a registration method like API-Keys.
17. Usage Limitations. For example allow only a certain amount of requests during a fixed time.