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:
- Best Practices for Designing a Pragmatic RESTful API: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
- 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
- OWASP REST Security Cheat Sheet: https://www.owasp.org/index.php/REST_Security_Cheat_Sheet
Current Status
Document the UI – I’ve found this tends to make the implementation clearerImplement in bootstrap, MVC4 with SQL Server backendDesign JSON API to access app- Implement JSON api using WebApi backend
- Replace MVC app with javascript client side framework, angular
- Swap the SQL Server backend for a No SQL database
- Replace the WebApi backend with an F# implementation
- Replace the WebApi backend with node.js