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

1. INTRODUCTIONTO REST API
Philip Aylesworth

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. 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. QUICK INTRO
• Client makes a request
http://example.com/sculptures/39!
• Server responds to request by sending data

5. {
"id":39,
"name":"Claim Post",
"artistId":30,
"artist":"Scott McKay",
"latitude":42.317359,
"longitude":-83.053128,
"url":"http://www.citywinds…"
}!
!
!

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. 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. 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. /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. /sculptures/39!
{
"id":39,
"name":"Claim Post",
"artistId":30,
"artist":"Scott McKay",
"latitude":42.317359,
"longitude":-83.053128,
"url":"http://www.citywinds…"
}

11. HTTPVERBS
• HTTP Request Methods describe action
• Create - POST
• Read - GET
• Update - PUT
• Delete - DELETE

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. •
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. RESOURCE NAMES
• No verbs in URI
• Plural or singular?
• Be consistent!
• Plural reads better

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. COMPOUND RESOURCES
• Where it makes sense:
/sculptures/39/artists
/artists/14/sculptures!
• No more than 2 deep
/artists/14/sculptures/donors

17. HIDE COMPLEXITY
• Use URI attributes for complexity
/sculptures?material=bronze&size=small!
/sculptures?fields=name,artist

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. 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. ERRORS
• Developers learn through errors
• Use HTTP status codes
• Return message - be verbose
• Optionally, include a URL to documentation

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. NAMING RETURNEDVALUES
• Doesn’t really matter as long as you are consistent
• If JSON is the default use camelCase since JSON is
JavaScript

23. AUTHENTICATION
• If possible use OAuth 2.0

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. 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. CONTACT INFO
• Phil Aylesworth
• Professor
• St. Clair College in Windsor Ontario
• paylesworth@stclaircollege.ca
• http://aylesworth.ca/phil/