REST API Design

Updated REST API Design slides for lecture at NCSU. Spring 2018.

Transcript

1. REST API Design
   Michael DeHaan
   NCSU, 2/2018
   

   View Slide

2. 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
   

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

6. 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/
   

   View Slide

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

   View Slide

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

   View Slide

9. 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”
   }
   

   View Slide

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

    View Slide

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

    View Slide

12. 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
    

    View Slide

13. 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”
    }
    ]
    

    View Slide

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

    View Slide

15. 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”,
    }
    

    View Slide

16. 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”,
    }
    

    View Slide

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

    View Slide

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

    View Slide

19. 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
    

    View Slide

20. 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
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

24. 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
    

    View Slide

25. 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)
    

    View Slide

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

    View Slide

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

    View Slide