I’ve spent some time designing the API for my internal project.
I’ve documented the design of the API here.
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.
As far as possible I’ve mapped this to valid HTTP verbs.
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.
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
Document the UI – I’ve found this tends to make the implementation clearer Implement in bootstrap, MVC4 with SQL Server backend Design JSON API to access app
- Implement JSON api using WebApi backend
- 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