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.

NOTE: This is WIP, any contribution is welcome!

Principles

TODO: Short introduction to main REST principles:

• Resources
• Actions
• Methods
• Statelessness
• Loose coupling
• ...

Criteria

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

1. Availability of Formal Description. TODO: Do we have this? Can we use Swagger for this?
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. Forms in Representations.
4. Number of Resource Types.
5. Versioned service endpoint. TODO: We will have an versioned service endpoint. Is this bad or not?
6. Scoping Information
7. Parameter Sources
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.