rest api
DESCRIPTION
Introduction the the REST API with some very opinionated best practices.TRANSCRIPT
![Page 1: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/1.jpg)
INTRODUCTION TO REST APIPhilip Aylesworth
![Page 2: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/2.jpg)
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
![Page 3: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/3.jpg)
WHAT IS REST• Representational State Transfer
• A network API (client/server)
• Not a protocol, very few hard rules
• Uses HTTP 1.1 protocol and URIs (Uniform Resource Identifiers)
![Page 4: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/4.jpg)
QUICK INTRO• Client makes a request
http://example.com/sculptures/39!
• Server responds to request by sending data
![Page 5: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/5.jpg)
{ "id":39, "name":"Claim Post", "artistId":30, "artist":"Scott McKay", "latitude":42.317359, "longitude":-83.053128, "url":"http://www.citywinds…" }!
!
!
![Page 6: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/6.jpg)
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
![Page 7: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/7.jpg)
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.
![Page 8: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/8.jpg)
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
![Page 9: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/9.jpg)
/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,!
![Page 10: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/10.jpg)
/sculptures/39!
{ "id":39, "name":"Claim Post", "artistId":30, "artist":"Scott McKay", "latitude":42.317359, "longitude":-83.053128, "url":"http://www.citywinds…" }
![Page 11: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/11.jpg)
HTTP VERBS• HTTP Request Methods describe action
• Create - POST
• Read - GET
• Update - PUT
• Delete - DELETE
![Page 12: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/12.jpg)
•
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/39create new sculpture with id 39
send data for sculpture 39
update sculpture 39
(create if doesn’t exist)
delete sculpture 39
![Page 13: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/13.jpg)
•
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/39create new sculpture with id 39
return error
send data for sculpture 39
update sculpture 39
(create error if doesn’t exist)
delete sculpture 39
![Page 14: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/14.jpg)
RESOURCE NAMES• No verbs in URI
• Plural or singular?
• Be consistent!
• Plural reads better
![Page 15: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/15.jpg)
VERSIONING• Always use a version /v1/sculptures
• Only change version number if something breaks
• Don’t change the version if features are added
![Page 16: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/16.jpg)
COMPOUND RESOURCES• Where it makes sense:
/sculptures/39/artists /artists/14/sculptures!
• No more than 2 deep
/artists/14/sculptures/donors
![Page 17: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/17.jpg)
HIDE COMPLEXITY• Use URI attributes for complexity
/sculptures?material=bronze&size=small!
/sculptures?fields=name,artist
![Page 18: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/18.jpg)
PAGINATION• To return partial sets:
/sculptures?limit=25&offset=50!
• limit and offset are easy to understand
• Should have default limit, such as 100
![Page 19: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/19.jpg)
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
![Page 20: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/20.jpg)
ERRORS• Developers learn through errors
• Use HTTP status codes
• Return message - be verbose
• Optionally, include a URL to documentation
![Page 21: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/21.jpg)
HTTP STATUS CODES• Use a small number of HTTP status codes
200 - Okay 201 - Created400 - Bad request401 - Unauthorized404 - Not found405 - Method not allowed500 - Internal server error
![Page 22: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/22.jpg)
NAMING RETURNED VALUES• Doesn’t really matter as long as you are consistent
• If JSON is the default use camelCase since JSON is JavaScript
![Page 23: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/23.jpg)
AUTHENTICATION• If possible use OAuth 2.0
![Page 24: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/24.jpg)
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
![Page 25: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/25.jpg)
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/
![Page 26: Rest API](https://reader034.vdocuments.us/reader034/viewer/2022052601/558fce501a28ab677f8b4606/html5/thumbnails/26.jpg)
CONTACT INFO• Phil Aylesworth
• Professor • St. Clair College in Windsor Ontario
• http://aylesworth.ca/phil/