REST API Design Michael DeHaan NCSU, 2/2018

Why REST § Web services are especially popular § Cross-language support § Users know how to use it § Reduce documentation § Reduce coding of a separate API/UI path

Things To Watch For § Consistency in URLS, Error Codes, Search, Pagination § Id/URL as primary identifier § Discoverability § Security: Authorization, Authentication, Privacy § Testing

History § XMLRPC 1998, Dave Winer – Userland/Microsoft § SOAP 1998, Winer/various – Microsoft § REST 2000, Roy Fielding, UC Irvine

When § YES: External Facing Services § MAYBE: Internal Services § But Also: § Message Buses/Queues § gRPC/other

API Roots § http://example.com/ § http://example.com/api/ § http://example.com/api/v1/ § http://example.com/api/v1/bands/ § http://example.com/api/v1/venues/

Verbs § CRUD: § Create – HTTP POST § Retrieve – HTTP GET § Update – HTTP PUT § Delete – HTTP DELETE

Versioning § GET http://example.com/api/ Returns HTTP 200 { “versions” : { “1.0” : “http://example.com/api/v1” }, “current” : “http://example.com/api/v1” }

Discoverability § GET http://example.com/api/v1/ Returns HTTP 200 { “venues” : http://example.com/api/v1/venues, “bands” : “http://example.com/api/v1/bands”, ”shows” : “http://example.com/api/v1/shows” }

Read: Collections § GET http://example.com/api/v1/bands [ { id: 1, href: “http://example.com/api/v1/bands/1” name: “Van Halen” }, … ]

Read: Specific Records § GET http://example.com/api/v1/bands/1 { id: 1, href: “http://example.com/api/v1/bands/1” name: “Van Halen” }

Search § GET http://example.com/api/v1/bands/?genre=rock [ { “id:” : 1, “name” : “Van Halen”, “href” : http://example.com/api/v1/bands/1, “genre” : “rock” } ] --- POSSIBLY: GET http://…/bands?founded_lt=1990&genre=rock GET http://…/bands?founded_in=1997,1998

Sorting § GET http://example.com/api/v1/bands/?order_by=name [ { “id:” : 1, “name” : “Van Halen”, “href” : http://example.com/api/v1/bands/1, “genre” : “rock” } ]

Pagination § http://example.com/api/v1/bands?page=1&size=50 { “page” : 1, “count” : 500, “prev” : None, “next” : “http://….” “last”: 500 “items” : [ … ] }

Create § POST http://example.com/api/v1/bands { “name” : “Rush”, “genre” : “Rock”, … } RETURNS HTTP 201 { “id” : 2, “name” : “Rush”, … “href” : “http://example.com/api/v1/bands/2”, }

Update § PUT http://example.com/api/v1/bands { “name” : “Rush”, “genre” : “Prog”, … } RETURNS HTTP 200 { “id” : 2, “name” : “Rush”, … “href” : “http://example.com/api/v1/bands/2”, }

Delete § DELETE http://example.com/api/v1/bands/1 RETURNS HTTP 204

General Error Codes § 200-299 Ok § 300-399 Redirects § 400-499 User Error § 500-599 Server Error

Specific Error Codes § 200 OK § 201 Created OK § 204 Deleted OK § 302 Redirect § 400 Bad Request § 401 Unauthorized § 403 Forbidden § 404 Not Found § 409 Conflict § 500 Internal Server Error

Authentication (Humans) § POST /api/v1/login § { “user” : “bob”, “password” : “12345” } § => { ”session-ID” : “ABCDEFGABCDEFG” } § GET /api/v1/something_restricted § HEADER: § X-SESSION-ID: “ABCDEFGABCDEFG” § Backend looks for headers § Session table keeps track of last time token was used § Sessions not used for ~30 minutes may expire (auto-log- out) § Client handles re-login or keep-alive as needed

Authentication (Machines) § Use X-API-KEY from separate table

Authorization § Because you are logged in does not mean you can get something § Backend code must HTTP 403 as appropriate

Filtering § Private records § If not admin, maybe /api/v1/users should only return you § Private fields § Don’t return passwords

Testing § Most REST frameworks should allow § Run database setup § Call some method that simulates a JSON GET/PUT/POST/DELETE § Use database methods to see if rows are present § Check error codes § For each URL § Check all verbs/methods § Unauthorized user § Authorized user § Forbidden user § Invalid inputs § Valid inputs, correct results

Finishing Up § How To Tell If It’s Good § Discoverability, Consistency § Everything Is Paginated § UI can render any page of O(1), not O(n) § Actions and Weird Verbs § Jobs & Job Templates § Complex Endpoints for UI Simplicity § (Whiteboard Discussion)

Database Tips § Go to Ignacio’s Lecture! § Index any field you may search by

Questions/ Example? § Questions? § Let’s lay out an app?