RESTful API Design

RESTful API Design discuss the high level guidelines to developing a proper API for a given web application. This talk was presented during Developer Talks vol2.0 June 2013.

LebGeeks is a local developer's community located in Lebanon. Developer Talks are quarterly gatherings in Beirut where a variety of programming related topics are discussed.

Transcript

2. Brief History
3. The Chosen ‘One’ Roy T. Fielding Representational State Transfer (REST) a term introduced and defined by Roy T. Fielding in 2000 as part of his doctoral dissertation “Architectural Styles and the Design of Network-based Software Architectures”. Fielding described REST as a software architecture style for distributed systems such as the World Wide Web. REST nowadays Is one of the most adopted styles in web services API design and arguably a “fashion statement”. It is also worth noting that Fielding also cofounded the Apache HTTP Server Project and is the former chairman of the non- profit Apache Software Foundation. Fielding has multiple other notable contributions to the modern Web architecture. Website: http://roy.gbiv.com/ Dissertation (URI): http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm (REST discussion is in Chapter 5).
4. “The Web is REST” Quoting Darrel Miller
5. Let’s talk Architecture
6. Basic High Level REST architecture describing a regular Client Request - Server Response scenario.
7. Designing a web service API is adding an extra control layer to handle this part! (As far as the receiving developer is concerned) Receiving developer being the one who will Implement your API in his(er) application.
8. REST architectural constraints are what makes it great. 1. Drastically minimizes the coupling between the client and server components. 2. Stateless 3. Layered System 4. Cacheable 5. Code on demand: (Optional) 6. Uniform Interface Your API design should comply with the constraints (1, 2, 3, 5, 6) to be considered RESTful (CoD is optional).
9. BUT, that’s not all. Good API design also takes into consideration the following: 1. Remember who the API is designed for. “ Treat others the way you wish to be treated ”. You API should be simple, intuitive and consistent. 2. It should be friendly so that the developer can explore it via the browser address bar. (For complex APIs, tools are generally developed to explore it. [Think Facebook Graph API Explorer]) 3. It should be efficient and fast without breaking the previous constraints. 4. It should comply with web standards (where it makes sense…)
10. HTTP Requests – CRUD mapping POST CREATE GET READ PUT UPDATE DELETE DELETE Resource POST create GET read PUT update DELETE delete /monkeys Create a new monkey Get list of monkeys Replace monkeys with new monkeys Delete all monkeys /monkeys/john Create a new monkey Get details of monkey john Upsert (update or insert) a monkey Delete monkey named john More complex variations apply, but they are out of the scope of this presentation.
11. Remember, your API complies with your applications Business Logic. You have the liberty to choose which actions apply and what type of response to return. We barely scratched the surface of a good API implementation. Grab me after the talk for more elaborate discussions (complex variations, versioning, pagination, formatting and hypermedia types to use, error handling / exceptions, authentication, Security, Documentation, Filtering & Searching, Compression, Caching, Request Limitations, HTTP Status Codes).
12. Let’s talk Code
13. For this presentation we’re going to be using PHP 5.4.6 running on an Apache 2.2.22 server with mongoDB 2.0.6 as our main data store. Why this particular stack? PHP is still an entry level web development language that is widely adopted. It has a non steep learning curve and is good- enough for developers with mid-level technical experience. This stack is highly documented and has a very large audience documenting their experiences with it online.
14. Slim micro-framework Why Slim? 1. Easy to install and configure. (Minimal system requirements) 2. Supports: 1. Routing 2. Sessions 3. Hooks 4. Logging 5. Error / Exception handling 6. MVC 7. HTTP Caching 3. Minimal footprint 4. Production ready
15. Composer If you haven’t used Composer yet to manage your project dependencies, you’re missing on A WHOLE LOT! Composer allows you to declare the dependent libraries your project needs and it will install (download) them in your project for you.
16. Installing Composer $ curl -sS https://getcomposer.org/installer | php $ sudo mv composer.phar /usr/local/bin/composer
17. Installing Slim $ cd /var/www/api/libs $ nano composer.json { "require": { "slim/slim": "2.*" } } Type the following:
18. Installing Slim $ composer install Run composer For more information about the awesomeness of composer go to the appendix for references
19. Rewrite Rules In order to follow the constraints described previously, we need to activate the RewriteEngine module in Apache and add the following to our .htaccess file.
23. This should be enough to get you started.
24. Happy Hacking…
25. my LebGeeks handle is Link- (also my Github handle)
26. References 1. REST Reference: http://en.wikipedia.org/wiki/Representational_state_transfer 2. Fielding’s Dissertation: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm 3. REST SO answer: http://stackoverflow.com/questions/1368014/ 4. API Design Reference: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api 5. Slim framework: http://docs.slimframework.com/#Installation 6. Composer: http://getcomposer.org/doc/00-intro.md