Developing RESTful APIs

Late Bloomer

Conclusion

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], Schema.org [7], and Alps.io [8].

Infos

  1. Request for Comments 707. A High-Level Framework for Network-Based Resource Sharing: https://tools.ietf.org/html/rfc707
  2. Fielding, Roy T. Architectural Styles and the Design of Network-Based Software Architectures . PhD dissertation, University of California, 2000, http://roy.gbiv.com/pubs/dissertation/top.htm
  3. Request for Comments 7231. Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content: https://tools.ietf.org/html/rfc7231
  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: https://www.iana.org/assignments/media-types/media-types.xhtml
  7. Schemas for structured data on the Internet: http://schema.org
  8. Application-Level Profile Semantics (ALPS): http://alps.io/spec/index.html
  9. OData standard by OASIS: https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=odata
  10. Request for Comments 5023. The Atom Publishing Protocol: https://tools.ietf.org/html/rfc5023
  11. JavaScript Object Notation (JSON): http://www.json.org
  12. OData Standard, Part 1, Core (ISO/IEC 20802-1:2016): https://www.iso.org/standard/69208.html
  13. OData Standard, Part 2, OData JSON Format (ISO/IEC 20802-2:2016): https://www.iso.org/standard/69209.html
  14. Open API Initiative: https://www.openapis.org
  15. "Swagger API" by Tim Schürmann, Linux Pro Magazine , issue 34, 2016, pg. 52, http://www.admin-magazine.com/Archive/2016/34/Swagger-and-OpenAPI-Specification-for-documents
  16. OpenAPI specification: https://github.com/OAI/OpenAPI-Specification
  17. Swagger tools: http://swagger.io/open-source-integrations/
  18. Swagger Petstore: http://petstore.swagger.io
  19. RAML: http://raml.org
  20. RAML v0.8: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md
  21. MuleSoft API Designer: https://www.mulesoft.com/platform/api/anypoint-designer
  22. MuleSoft API Workbench: http://apiworkbench.com
  23. RAML 100 Tutorial: http://raml.org/developers/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

SINGLE ISSUES
 
SUBSCRIPTIONS
 
TABLET & SMARTPHONE APPS
Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus