O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.

Rest API

394 visualizações

Publicada em

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

Publicada em: Tecnologia, Design
  • Seja o primeiro a comentar

  • Seja a primeira pessoa a gostar disto

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/

×