Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Rest API

387 views

Published on

Introduction the the REST API with some very opinionated best practices.

Published in: Technology, Design
  • Be the first to comment

  • Be the first to like this

Rest API

  1. 1. INTRODUCTIONTO REST API Philip Aylesworth
  2. 2. WHO AM I • Phil Aylesworth • Professor since 2000 • St. Clair College in Windsor Ontario • Teach Linux, HTML, CSS, JavaScript • Previously a Unix Administrator and Networking Consultant
  3. 3. WHAT IS REST • Representational StateTransfer • A network API (client/server) • Not a protocol, very few hard rules • Uses HTTP 1.1 protocol and URIs (Uniform Resource Identifiers)
  4. 4. QUICK INTRO • Client makes a request http://example.com/sculptures/39! • Server responds to request by sending data
  5. 5. {
 "id":39,
 "name":"Claim Post",
 "artistId":30,
 "artist":"Scott McKay",
 "latitude":42.317359,
 "longitude":-83.053128,
 "url":"http://www.citywinds…"
 }! ! !
  6. 6. YOU ALREADY DO APIS • If you do server-side coding, you are doing APIs /show_all_artists.php
 /show_artist.php?id=23
 /update_artist.php?id=23&name=Jane+Doe
 /delete_artist.php?id=23
  7. 7. IT’S ALL ABOUT DATA • Often used to query or set data in a database • But it can also be static files • CRUD - Create / Read / Update / Delete • Return data can be any format: • JSON, XML,Text, HTML, CSV, etc.
  8. 8. RESOURCE • Your API might have many resources
 Eg: sculptures, artists, donors, etc. • For each resource we should have two URLs • One for the collection: 
 /sculptures • One for individual items in collection:
 /sculptures/39
  9. 9. /sculptures! [
 {
 "id":29,
 "name":"Anne",
 "artistId":13,
 "artist":"Leo Mol",
 "latitude":42.316921,
 "longitude":-83.054811,
 "url":"http://www.citywindsor.ca/res…"
 },
 {
 “id":25,
 "name":"Audio Corridor",
 "artistId":9,
 "artist":"Ian Lazarus",
 "latitude":42.315751,
 "longitude":-83.057804,
 "url":"http://www.citywindsor.ca/res…"
 },
 {
 "id":9,
 “name":"Bell Measure",
 "artistId":24,
 "artist":"Stephen Cruise",
 "latitude":42.3112,!
  10. 10. /sculptures/39! {
 "id":39,
 "name":"Claim Post",
 "artistId":30,
 "artist":"Scott McKay",
 "latitude":42.317359,
 "longitude":-83.053128,
 "url":"http://www.citywinds…"
 }
  11. 11. HTTPVERBS • HTTP Request Methods describe action • Create - POST • Read - GET • Update - PUT • Delete - DELETE
  12. 12. • Resource POST (Create) GET (Read) PUT
 (Update) DELETE
 (Delete) /sculptures create a new sculpture list all sculptures replace all sculptures with new sculptures delete all sculptures /sculptures/39 create new sculpture with id 39 send data for sculpture 39 update sculpture 39 (create if doesn’t exist) delete sculpture 39
  13. 13. • Resource POST (Create) GET (Read) PUT
 (Update) DELETE
 (Delete) /sculptures create a new sculpture list all sculptures replace all sculptures with new sculptures delete all sculptures /sculptures/39 create new sculpture with id 39 return error send data for sculpture 39 update sculpture 39 (create error if doesn’t exist) delete sculpture 39
  14. 14. RESOURCE NAMES • No verbs in URI • Plural or singular? • Be consistent! • Plural reads better
  15. 15. VERSIONING • Always use a version
 /v1/sculptures • Only change version number if something breaks • Don’t change the version 
 if features are added
  16. 16. COMPOUND RESOURCES • Where it makes sense: /sculptures/39/artists
 /artists/14/sculptures! • No more than 2 deep /artists/14/sculptures/donors
  17. 17. HIDE COMPLEXITY • Use URI attributes for complexity /sculptures?material=bronze&size=small! /sculptures?fields=name,artist
  18. 18. PAGINATION • To return partial sets: /sculptures?limit=25&offset=50! • limit and offset are easy to understand • Should have default limit, such as 100
  19. 19. FORMATS • Output whatever formats you or your users, need:
 JSON, XML, CSV, HTML • Fairly easy to map one to another /sculptures.json
 /sculptures/39.json
 /sculptures.xml! • JSON is a good default
  20. 20. ERRORS • Developers learn through errors • Use HTTP status codes • Return message - be verbose • Optionally, include a URL to documentation
  21. 21. HTTP STATUS CODES • Use a small number of HTTP status codes
 200 - Okay
 201 - Created
 400 - Bad request
 401 - Unauthorized
 404 - Not found
 405 - Method not allowed
 500 - Internal server error
  22. 22. NAMING RETURNEDVALUES • Doesn’t really matter as long as you are consistent • If JSON is the default use camelCase since JSON is JavaScript
  23. 23. AUTHENTICATION • If possible use OAuth 2.0
  24. 24. DOMAIN NAMES • Recommend using: • api.example.com for your API • developer.example.com for your documentation • Redirect http://api.example.com/ to 
 http://developer.example.com • Use HTTPs if possible
  25. 25. REFERENCES • http://www.sitepoint.com/rest-can-you-do-more- than-spell-it-1/ • http://en.wikipedia.org/wiki/ Representational_state_transfer • https://www.ibm.com/developerworks/ webservices/library/ws-restful/
  26. 26. CONTACT INFO • Phil Aylesworth • Professor • St. Clair College in Windsor Ontario • paylesworth@stclaircollege.ca • http://aylesworth.ca/phil/

×