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

• paylesworth@stclaircollege.ca

• http://aylesworth.ca/phil/