Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Designing for API (with Swagger and Scala)

Designing for API (with Swagger and Scala)

  • Swagger support
    • type-safe documentation
    • contract-first API sandbox
    • machine readable
  • "A node, once deployed, cannot be changed"
  • ScalaBay - API Design Antipatterns by Manish Pandit
  • HTTP actions and their meanings
    • POST to C reate or upsert
    • GET to R ead, retrieve, or search
    • PUT (or better yet PATCH) to U pdate
    • DELETE to D elete
  • HTTP codes antipatterns
    • always return HTTP 200 OK
      • {"success":false} (!)
    • always returning HTTP 401 Unauthorized for auth failures
      • Use 401 to indicate that the client needs to authenticate
      • Use 403 Forbidden to indicate that the client's credentials don't allow access to the requested resource
      • 401 to say "Come back with a key"
      • 403 to say "Your key doesn't fit the lock"
  • General HTTP codes
    • 2xx for success
    • 3xx for redirects/caching
    • 4xx for request/client errors
    • 5xx for server errors
  • Useful yet less often used HTTP codes
    • 204 for returning after a delete
    • 409 for failed database constraint
    • 405 for method not supported
    • 413 for trying to ask for too much data
    • 418 for validation failure
  • Async operations and return HTTP 202 Accepted
    • {"statusUrl" : <some URL>}
  • Entities are not instances
  • Namespace your resources in collection
  • Use paths and identifiers to traverse
  • /pets/1234 for an instance 1234 of pets
    • id is implied
  • other attributes in path
  • /resource/meta or /collection/meta for resource description (META pages)
  • Consider swagger or IODocs - documentation generators
  • Accept cookies as a fallback, but prefer a query parameter or HTTP request header
  • Stateless always
  • Requests modify or read a resource
  • Maintain state in database
    • no transient state changes on server
  • Versioning
    • 301 to redirect/retire APIs
  • Caching
    • Use HTTP headers
  • API Antipatterns : APICon SF by Manish Pandit
  • Always specify a qualifier in the path when accessing resource(s) in a collection...except when accessing via the primary ID (it's implied)
    • /movies/name/{name}
    • /users/1234
    • /device/type/bdplayers
  • Always think about the path to the resource as /collection/resource identifier/value
    • ...and manipulate it via verbs
  • Resource properties in paths acceptable /movies/rating/G
  • Resource discovery via META pages
    • /collection/meta
    • /resource/meta
  • DELETE for nulling a value
    • DELETE /movies/{id}/rating
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.