« Previous 1 2 3 4

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.

« Previous 1 2 3 4

Buy this article as PDF

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

Buy ADMIN Magazine

SINGLE ISSUES
Print Issues
Digital Issues
 
SUBSCRIPTIONS
Print Subs
Digisubs
 
TABLET & SMARTPHONE APPS
Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Lead Image © smeagorl, 123RF.com
    Swagger and OpenAPI Specification for documents
    A REST API is especially useful for a developer if the API provider extensively documents the methods used. The Swagger tools not only semiautomatically generate an API reference, but a matching client SDK for many programming languages, as well.
    more »
  • Photo by Aidas Ciziunas, Unsplash.com
    Haskell framework for the web
    The Yesod web framework includes a Haskell compiler on top of the standard web technologies, such as HTML, JavaScript, and CSS, with aggressive optimization and function checks for correctness.
    more »
  • Lead Image © Sergey Nivens, 123RF.com
    Single sign-on like the big guys
    Keycloak is a robust and mature project that provides a modern single sign-on authorization experience and centralized authentication of your apps.
    more »
  • Lead Image © Aleksey Mnogosmyslov, 123RF.com
    DevSecOps with DefectDojo
    The DefectDojo vulnerability management tool helps development teams and admins identify, track, and fix vulnerabilities early in the software development process.
    more »
  • Contact

    Contact

    more »
comments powered by Disqus