Upload
phil-aylesworth
View
125
Download
3
Tags:
Embed Size (px)
DESCRIPTION
Introduction the the REST API with some very opinionated best practices.
Citation preview
INTRODUCTION TO REST APIPhilip Aylesworth
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
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)
QUICK INTRO• Client makes a request
http://example.com/sculptures/39!
• Server responds to request by sending data
{ "id":39, "name":"Claim Post", "artistId":30, "artist":"Scott McKay", "latitude":42.317359, "longitude":-83.053128, "url":"http://www.citywinds…" }!
!
!
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
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.
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
/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,!
/sculptures/39!
{ "id":39, "name":"Claim Post", "artistId":30, "artist":"Scott McKay", "latitude":42.317359, "longitude":-83.053128, "url":"http://www.citywinds…" }
HTTP VERBS• HTTP Request Methods describe action
• Create - POST
• Read - GET
• Update - PUT
• Delete - DELETE
•
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
•
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
RESOURCE NAMES• No verbs in URI
• Plural or singular?
• Be consistent!
• Plural reads better
VERSIONING• Always use a version /v1/sculptures
• Only change version number if something breaks
• Don’t change the version if features are added
COMPOUND RESOURCES• Where it makes sense:
/sculptures/39/artists /artists/14/sculptures!
• No more than 2 deep
/artists/14/sculptures/donors
HIDE COMPLEXITY• Use URI attributes for complexity
/sculptures?material=bronze&size=small!
/sculptures?fields=name,artist
PAGINATION• To return partial sets:
/sculptures?limit=25&offset=50!
• limit and offset are easy to understand
• Should have default limit, such as 100
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
ERRORS• Developers learn through errors
• Use HTTP status codes
• Return message - be verbose
• Optionally, include a URL to documentation
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
NAMING RETURNED VALUES• Doesn’t really matter as long as you are consistent
• If JSON is the default use camelCase since JSON is JavaScript
AUTHENTICATION• If possible use OAuth 2.0
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
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/
CONTACT INFO• Phil Aylesworth
• Professor • St. Clair College in Windsor Ontario
• http://aylesworth.ca/phil/