Designing for API (with Swagger and Scala)

Designing for API (with Swagger and Scala).md

Designing for API (with Swagger and Scala)

• Another API-Blueprint, RAML and Swagger Comparison
  • JSON
  • Reverb - company behind the project
  • API design approach - bottom-up (FIXME what does this mean?)
  • API version metadata
  • Scala for server and client code possible
  • community stats favors...swagger (stackoverflow, github, google search for "swagger rest")
• OSCON 2014 - API Ecosystem with Scala, Scalatra, and Swagger at Netflix
• Scalatra
  • Ligthweight HTTP wrapper
  • Excellent swagger support
  • ScalatraSpec
  • .war-based deployment

• 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://some.api.com/movies?start=0&count=10&sortBy=name&fields=name,cast,releaseDate
• 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
• HATEOAS
• /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