Upgrade to Pro — share decks privately, control downloads, hide ads and more …

REST API Design

REST API Design

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

Michael DeHaan

February 06, 2018
Tweet

More Decks by Michael DeHaan

Other Decks in Technology

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