RESTful APIs — A quick intro
An API(short for Application Programming Interface) is a set of rules and specifications that enable different software programs to communicate with each other. However the term is mostly used to refer to web services.
REST (short for Representational State Transfer) is an architectural style for building web services which focuses on accessing named resources using HTTP requests.
What are some Characteristics of a REST API?
State in simple words is the data that the server requires to fulfill a request. In REST APIs, the necessary state is contained in the request itself.
Responses should be implicitly or explicitly defined as cacheable or not. Caching, if used well, can greatly improve performance and scalability of the API.
iii) Uniform Interface:
The interface between the client and server should be decoupled to enable each to function independently.
Separation of concerns via uniform interface ensures that the client is not concerned with data storage and the server has nothing to do with the user interface. Servers and clients can be developed independently as long as the interface remains unaltered.
So why RESTful APIs?
1. They are easy and fast to build- no need for toolkits.
2. They are lightweight
3. The results from REST APIs are in JSON format which makes them human readable.
That said, there are a few things to keep in mind when building a RESTful API.
i) Status Codes:
Your API should always return correct and accurate HTTP status codes. This helps the users and network equipment understand better the result output by the request and take appropriate action. Here is a comprehensive list of HTTP status codes.
ii) Resource naming:
When naming your resources, you should use nouns and not verbs. The nouns should also be in plural eg: /books or /users.
Always ensure to set the version of your API. As much as possible avoid using dot notation eg: /my-api/v2/ instead of /my-api/v2.0/.
iii) Use JSON:
Besides being the preferred format for presenting request output in REST, JSON is easily readable by humans and is usable in nearly every programming language.
iv) Error handling:
Your API should return clear error massages accompanied by the correct HTTP status codes.
Limit the number of records output at once.
This is my opinion one of the most important things to have when releasing your API for use by other developers. It not only helps them understand how to use it but makes it easy for you as well when fixing bugs or extending it.
This is obviously not the complete list of things to consider but they are the probably the most important(I stand to be corrected).
For further reading, check out http://www.restapitutorial.com/ and http://www.andrewhavens.com/posts/20/beginners-guide-to-creating-a-rest-api/. I found these two really informative.