Internal project – design the API

~ David Cameron

I’ve spent some time designing the API for my internal project.

I’ve documented the design of the API here.

Key Points

Session 

Following best practices, I’ve avoided including the login and password with each request. Instead there is a session service. Call this service to create a new session and get a session token in response. In addition I’ve included a method to end the session early. The intention that the session token would expire. Making a call to any of the methods on the API would reset the timeout.

HTTP

As far as possible I’ve mapped this to valid HTTP verbs.

Difficulties

One difficulty I ran into was how to provide a nice mechanism to mark a post a liked. It didn’t make sense to mark a status item as liked by making a PUT request with the entire status item. The best option was to add a status/like URL, under the status URL.

Resources

There are a sack of really good resources out there for this:

  1. Best Practices for Designing a Pragmatic RESTful API: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
  2. The Good, the Bad, and the Ugly of REST APIs: http://broadcast.oreilly.com/2011/06/the-good-the-bad-the-ugly-of-rest-apis.html
  3. OWASP REST Security Cheat Sheet: https://www.owasp.org/index.php/REST_Security_Cheat_Sheet

Current Status

  1. Document the UI – I’ve found this tends to make the implementation clearer
  2. Implement in bootstrap, MVC4 with SQL Server backend
  3. Design JSON API to access app
  4. Implement JSON api using WebApi backend
  5. Replace MVC app with javascript client side framework, angular
  6. Swap the SQL Server backend for a No SQL database
  7. Replace the WebApi backend with an F# implementation
  8. Replace the WebApi backend with node.js

Published by David Cameron

Leave a comment