OpenAPI Specification

OpenAPI Specification v2.0 – formerly known as Swagger RESTful API Documentation Specification.

Swagger™ is a project used to describe and document RESTful APIs.

The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools.

Google vs. Oracle : API vs. implementation

Slashdot is running the story about the Google vs. Oracle court case.  I thought this bit was rather brilliant:

Schwartz’s second attempt at the breakfast menu analogy went much better, as he explained that although two different restaurants could have hamburgers on the menu, the actual hamburgers themselves were different — the terms on the menu were an API, and the hamburgers were implementations.”

Best Practices for Designing a Pragmatic RESTful API

An API is a user interface for developers. Put the effort in to ensure it’s not just functional but pleasant to use.

Vinay Sahni has a rather lengthy, detailed, and well-rounded post on how to design a good RESTful API.  It covers pretty much everything from URL structures and parameters, request methods, to error handling, documentation, and coding style.