WEB API best practices

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!

First GA of RESTeasy Released

On 21 January JBoss announced the first GA of RESTeasy was released

Like any other java nuts and bolts framework it is “certified” against JAX-RS specification which makes me worry about being a heavy approach.

JBoss RESTEasy is a framework that allows you to write RESTFul Web Services in Java. It is a fully certified and portable implementation of JAX-RS specification.

It can be run in Servlet container such Tomcat but the full benefits come when integrated with JBoss AS. What is new is that despite JAX-RS which is a server side specification the JBoss team innovated on the client side and they implemented JAX-RS Client framework to speed the development process.


* Fully certified JAX-RS implementation
* Portable to any app-server/Tomcat that runs on JDK 5 or higher
* Embeddedable server implementation for junit testing
* Rich set of providers for: XML, JSON, YAML, Fastinfoset, Atom, etc.
* JAXB marshalling into XML, JSON, Fastinfoset, and Atom as well as wrappers for arrays, lists, and sets of JAXB Objects.
* Asynchronous HTTP (Comet) abstractions for JBoss Web, Tomcat 6, and Servlet 3.0
* EJB, Spring, and Spring MVC integration
* Client framework that leverages JAX-RS annotations so that you can write HTTP clients easily (JAX-RS only defines server bindings)

I know that it sounds like another heavy J2EE framework but give it a try.