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!

Comments

7 Responses to “WEB API best practices”

  1. andrei on February 18th, 2009 4:19 am

    Hi,

    I find your post very interesting and I would like to know more about SOA. Can you please recommend me a book?

  2. CRISTIANO on February 20th, 2009 8:54 am

    I recommend you a tool: ENUNCIATE – http://enunciate.codehaus.org. This tool can grow your productivity and can give you a better view about different Web services solutions. As they say: Enunciate is an engine for creating, maintaining, and deploying your rich Web service API for the Java platform. Good luck!

  3. Rafael Vega on February 20th, 2009 2:53 pm

    Great post!
    Can you point us to some REST API authentication/security recommendations?

  4. bserban on February 21st, 2009 2:54 pm

    Hi Andrei,

    I recommend you to read these two books Building Scalable Web Sites, about how flickr was build, and Scalable Internet Architectures, i found them great.

  5. bserban on February 22nd, 2009 10:02 am

    Rafael,

    I am thinking to post a blog entry about authentication and security in REST Applications. So far i have used:
    * cookies/tokens (depends on the api) to maintain the session
    * application ids to limit the usage
    * after every interaction provide a new token and validate it at the next call
    * and of course, you could use digital signature.

    bserban

  6. Rafael Vega on February 24th, 2009 6:39 am

    Thanks!
    I just finished reading the RESTful Web Services book by Leonard Richardson and Sam Ruby. I highly recommend it for anyone interested in this subject.
    I’m going with a request signing authentication schema, similar to what the Amazon S3 service does.

  7. PI on October 5th, 2009 11:18 am

    Thanks!
    I just finished reading the RESTful Web Services book by Leonard Richardson and Sam Ruby. I highly recommend it for anyone interested in this subject.
    I’m going with a request signing authentication schema, similar to what the Amazon S3 service does.