Recently I had to do an API for my application. Coming from the world of J2EE, my first thought was to make a web service based on SOAP, but I soon realized that this type of J2EE web services is heavy. They are slow and cumbersome and requires the use of specialized frameworks or j2ee containers that support such services. After a careful study of the problem I have concluded that the best solution would be using services REST like, based on XML and JSON.

Read more about REST services in Roy Thomas Fielding’s dissertation paper Representational State Transfer (REST). This will give you some insides about what REST should be.

Anyway, I don’t plan to write about REST, I just want to share you some of the best practices for developing an web API. When you design an API you should be aware that from the moment that it’s launched to the public, changing it will become impossible An API evolves over time, but because you already have customers, you need to be compatible with earlier versions, otherwise customers will leave

Some things to keep in mind.

1. Create a subdomain for the API, it will help you a lot to load balance your traffic. You could also have an URL path, but still will have the same entry point as the main application. However, the best is to create a subdomain for API.
2. Version the API by including the version in the URL. This will help you stay compatible with earlier versions of the API, until everyone will upgrade to new version. Example: 

      1: api.mydomain.net/v1/my_api_name/my_entry_point

3. You should split your API in packages by using the URL namespace, Example

      1: api.mydomain.net/v1/namespace1/my_entry_point1

      2: api.mydomain.net/v1/namespace2/my_entry_point2

4. Create API keys. You need a way to see who is using your API and how. If you do not have such keys you’ll never know how many customers you have.This practice would allow the measurement of service usage by customers and to impose limits for use.
5. Monitor everything. Use your access log to monitor use of services. You need to know how many accesses, errors, readings, queries, changes you have for each service.
6. Create API documentation with examples. Create applications for demo purposes.
7. Use GET for read and POST for change. If the changes do not require a large volume of data, transmit data via POST URL, in this way you can log them into access.log. This is useful for statistics.
8. You should use data collected in access logs to improve service or to create  personalization and recommendation engines

Keep an eye on this post, because I intend to update it regularly. Know other good practices? If yes, then leave a message. Thanks!