https://devsummit.aspirationtech.org/index.php?title=Designing_RESTful_API%27s&feed=atom&action=historyDesigning RESTful API's - Revision history2024-03-28T14:18:28ZRevision history for this page on the wikiMediaWiki 1.35.1https://devsummit.aspirationtech.org/index.php?title=Designing_RESTful_API%27s&diff=982&oldid=prevVivian: 1 revision imported2015-05-20T21:30:14Z<p>1 revision imported</p>
<p><b>New page</b></p><div>Facilitated by Evan Henshaw-Plath, [http://protest.net protest.net]<br />
<br />
Evan has designed more than his fair share of API's, and he will share his methodology and processes for RESTful API design, and discuss what distinguishes a good API from a poor one.<br />
<br />
[[Designing RESTful API's/notes]]<br />
<br />
=== Notes ===<br />
''raw notes''<br />
<br />
Why do a session?<br />
* Folks sing SOAP <- not good<br />
* People dont seem to know about REST APIs<br />
* Began with PhD document<br />
<br />
Why is SOAP bad (or different)?<br />
* Simple Object Access Protocol<br />
* Lots of API Protocols<br />
* XMLRPC came out and was simple, then larger groups created SOAP<br />
* RPC - Remote Procedure Call<br />
** Predates Internet. It's calling a method that is on a remote resource<br />
* Offers list of discovery and schema<br />
<br />
REST<br />
* That each URL is a resource<br />
* Each HTTP method is an action<br />
* Can provide same URIs for web application via browser and via API<br />
* Original Standard created by Roy Felding<br />
** Current implemtations are often mutations<br />
* not language specific (only languages that can utilize HTTP)<br />
* WADDLE ??<br />
* Format agnostic<br />
** Return close to internal data format<br />
** Can return HTML, XML, JSON<br />
*** .html, .json<br />
*** MIME Types<br />
* Ruby and Django are often better at RESTful APIs<br />
<br />
HTTP Verb (Actions)<br />
* Get - read<br />
* Post - create (update)<br />
* Put - update (create)<br />
** Not usually used<br />
** Like file upload<br />
** Have to know what the URL is, not good for auto-incrementing<br />
* Delete - delete<br />
** Not usually used<br />
** Remove resource<br />
<br />
CRUD<br />
* create, read, update, delete<br />
* The basic building blocks of web applications<br />
* REST HTTP methods are same as CRUD<br />
<br />
WSDL<br />
* Offeres discovery of API<br />
* Do we need it?<br />
** vs documentation<br />
** discovery does not actually offer ability to create application<br />
<br />
Design API<br />
* Write first<br />
* Build a sample client<br />
* FireEagle<br />
** release client implementation in many languages<br />
* Determine what is returned<br />
** As much as possible that is easier for you as provider<br />
** Objects<br />
*** Not usually worth filtering fields/parts of an object<br />
*** Cache objects<br />
** Lists are different<br />
*** Offset problems with updating and listing at the same<br />
*** Pagination<br />
**** Ability to paginate or not? Some instances do not let pages, or a limited amount of pages<br />
**** Do not paginate if there is a JOIN in query <br />
**** List of IDs (not the whole object), then get objects separate<br />
*** Need to index database<br />
**** Nothing in WHERE clause should not be indexed<br />
**** Better to have many requests that are cacheable than fewer requests with lots of processing time<br />
***** HTTP is faster than MySQL<br />
**** Example: FriendFeed<br />
***** Millions of requests a day<br />
***** Could have done fewer requests with larger queries without index<br />
* Conditional GET to determine if there is a change<br />
** Always provide Last MOdified in HTTP Headers<br />
** eTag -> MD5 hash of content<br />
* Output Standards<br />
** If data can be in ATOM, do it so that the data is more distributable<br />
** iCal, not great standard, easy to implement<br />
** if can use easy, popular standards, good to use<br />
* Frameworks often have REST implementations<br />
* example exposue: example.org/api/v1/customer/1/find?blah=1<br />
* By putting API in other folder, can filter and put that load on a different server<br />
* How are building people building REST APIs???????? (public)<br />
* What to use in Standard?<br />
** REST design that works like RPC<br />
** Use response formats<br />
** important to eTags and Last Modified<br />
** Put and Delete are not that useful<br />
** Get and Post are useful<br />
* Good URI<br />
** is guessable<br />
** /api/categories/list/format<br />
** /api/categories/1/post/all/xml<br />
** NO definte right, but just by example that are being used<br />
<br />
REST vs RPC<br />
* REST has object and verb (in headers)<br />
* RPC has verb with parameters<br />
<br />
Upgrade APIs<br />
* use version paths<br />
* people dont upgrade<br />
* never remove anything<br />
** or make sure that previous data is put to null<br />
* mapping and translation from API to DB can be useful<br />
<br />
Web Frameworks<br />
* PHP -> Symfony, CakePHP, CodeIgnitor, Zend<br />
* Ruby on Rails<br />
* Django<br />
* ORM<br />
** Object Relational Model<br />
** Translating data from DB to Object<br />
<br />
JSON<br />
* a lot of new REST APIs output JSON<br />
* serialize JS objects<br />
* Easily parsing<br />
<br />
User Authentication<br />
* Twitter<br />
** AuthBasic<br />
** Twitter apps need password<br />
* Token based<br />
** Google offers APIs<br />
** offer tokens instead of username/password<br />
** Token in HTTP Headers, or URI parameter<br />
* Consitent Way?<br />
** OAuth<br />
** originally developed for Twitter<br />
** Consitent set of libraries for multiple languages <br />
** Example<br />
*** FireEagle<br />
**** iPhone has permission to tell Facebook which asks FireEagle for a token on behalf<br />
<br />
Front Caching<br />
* ModProxy or Squid<br />
* Problems arise with Authentication<br />
<br />
Ruby on Rails<br />
* 7 Holy verbs<br />
* There are sometimes different actions that need to happen (ie Registration Status update)<br />
<br />
Future of Web Standards<br />
* Jabber (XMPP extensible messaging presence protocol) and REST<br />
** Sends XML<br />
* Publish and Subscribe<br />
* Problem: ask every 5 minutes to recieve NO for 5 months<br />
* Use XMPP to use Signals instead of Pulls<br />
* HTTP is more overhead compared to XMPP<br />
** HTTP(S) has only single connections each time<br />
** XMPP caches messages<br />
* Web Server is repsonsible to tell about changes<br />
* Web Hooks<br />
** Like TracBack<br />
** Good for few requests<br />
** Can't handle 20,000/min<br />
* XMPP<br />
** Can handle 20,000/min<br />
* Twitter<br />
** Offers ?? XMPP</div>Vivian