An Overview of REST Metadata Formats

Although the REST community initially took a stance against metadata for REST APIs, a number of metadata standards have none-the-less emerged over the last couple of years, mainly fueled by the need to document APIs for their consumers.

...

The common goal of current metadata formats for REST APIs is to specify

• Entry point(s)
• Resource paths
• Methods to access these resources (GET, POST, PUT, etc.…)
• Parameters that need to be supplied with these methods (Query, Template, HTTP Header, etc.)
• Formats of inbound / outbound messages/representations (JSON Schema, XML Schema, Relax NG, etc.)
• Status codes and error/fault messages
• Documentary information (descriptions, etc.) for all these

All these are somewhat derived from the principles underlying REST APIs – i.e. those of resources, representations etc. Non-functional aspects of APIs, like for example authentication (Basic, OAuth, SAML, etc.), security (encryption, signatures, etc.) and versioning are unfortunately still poorly addressed by most REST metadata standards. This is where the WS-* standards “shine”, but it is also what many refer to as WS-(death-star) – indicating the complexity of the WS standards that might ultimately lead to their demise. Hopefully the REST community will align around common standards and best practices more successfully than vendors did in the SOAP-domain around 10 years ago.

...

From: http://apiux.com/2013/04/09/rest-metadata-formats/

Secure Your REST API... The Right Way

Secure Your REST API... The Right Way:

At Stormpath we spent 18 months researching best practices, implementing them in the Stormpath API, and figuring out what works. Here’s our playbook on how to secure a REST API.

Brian Sletten on RESTful API Design

Brian Sletten on RESTful API Design:

Brian Sletten, the author of the DZone REST Refcard dispels pre-conceived notions about REST API design while going over Representation Design, Versioning, and more...

Designing a Beautiful REST+JSON API

Designing a Beautiful REST+JSON API:

In this presentation, Les Hazlewood - Stormpath CTO and Apache Shiro PMC Chair - will share all of the golden nuggets learned while designing, implementing and supporting JSON-based REST APIs, using examples from a clean real-world REST+JSON API built with Java technologies.

What Legos Teaches Us About REST API Testing

What Legos Teaches Us About REST API Testing:

Learn about REST API Testing Patterns

Thoughts on RESTful API Design

Thoughts on RESTful API Design by Geert Jansen

This essay is an attempt to put down my thoughts on how to design a real-world yet beautiful RESTful API. It draws from the experience I have gained being involved in the design of theRESTful API for Red Hat’s Enterprise Virtualization product, twice. During the design phase of the API we had to solve many of the real-world problems described above, but we weren’t willing to add non-RESTful or “RPC-like” interfaces to our API too easily.

In my definition, a real-world RESTful API is an API that provides answers to questions that you won’t find in introductory texts, but that inevitably surface in the real world, such as whether or not resources should be described formally, how to create useful and automatic command-line interfaces, how to do polling, asynchronous and other non-standard types of requests, and how to deal with operations that have no good RESTful mapping.

A beautiful RESTful API on the other hand is one that does not deviate from the principles of RESTful architecture style too easily. One important design element for example that is not always addressed is the possibility for complete auto-discovery by the API user, so that the API can be used by a human with a web browser, without any reference to external documentation. I will discuss this issue in detail in Forms.

Author: Geert Jansen <gjansen@redhat.com>

https://github.com/geertj/restful-api-design