Developing RESTful APIs

Late Bloomer


REST is an abstract idea designed to better structure the behavior of a software architecture. The approach demands discipline and requires an additional level of abstraction on top of the desired solution. Not everyone is enamored, and how meaningful this overhead is depends on the API's intended use. How long do the developers intend to maintain it? How quickly do you want to be able to introduce it to new developers? How compatible should it be with other solutions? These are just a few of the fundamental issues.

The sample API on the Sinatra server is designed to illustrate the abstraction. To create a full RESTful API, developers would need to elaborate the RAML design and make a sensible choice for the data format standard.

The advantage of REST is the concept of the "Hypertext As The Engine Of Application State" (HATEOAS). Roughly this means that, based on the existing hypertext, any client should know the current application state and be able to enter the next state via the hypertext mechanisms.

The sample does not implement this concept in a satisfactory way. The client can tell from the response how to access a single contact, but it does not learn how to create it or how to structure the data to do so. The next step would be to integrate this information into the format itself.

Some standard formats offer to add POST templates or schema descriptions to the protocol. It makes a lot of sense to look at the registered formats and protocols such as IANA [6], [7], and [8].


  1. Request for Comments 707. A High-Level Framework for Network-Based Resource Sharing:
  2. Fielding, Roy T. Architectural Styles and the Design of Network-Based Software Architectures . PhD dissertation, University of California, 2000,
  3. Request for Comments 7231. Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content:
  4. Richardsen, Lennard and Mike Amundsen. RESTful Web APIs: Services for a Changing World . O'Reilly, 2013
  5. Amundsen, Mike. Building Hypermedia APIs with HTML5 & Node – Creating Evolvable Hypermedia Applications . O'Reilly, 2011
  6. Media types registered with IANA:
  7. Schemas for structured data on the Internet:
  8. Application-Level Profile Semantics (ALPS):
  9. OData standard by OASIS:
  10. Request for Comments 5023. The Atom Publishing Protocol:
  11. JavaScript Object Notation (JSON):
  12. OData Standard, Part 1, Core (ISO/IEC 20802-1:2016):
  13. OData Standard, Part 2, OData JSON Format (ISO/IEC 20802-2:2016):
  14. Open API Initiative:
  15. "Swagger API" by Tim Schürmann, Linux Pro Magazine , issue 34, 2016, pg. 52,
  16. OpenAPI specification:
  17. Swagger tools:
  18. Swagger Petstore:
  19. RAML:
  20. RAML v0.8:
  21. MuleSoft API Designer:
  22. MuleSoft API Workbench:
  23. RAML 100 Tutorial:

The Author

Marcus Nasarek has focused on Linux for many years and is a huge fan of scripting, Ruby, and Raspberry Pi projects.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy ADMIN Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus