API Design Ebook

- https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf
- Brian Mulloy

- Keep your base URL simple and intuitive
- Keep verbs out of your base URLs
- Use HTTP verbs to operate on the collections and elements. (POST, GET, PUT, and DELETE -- CRUD)
- Plural nouns and concrete names (Being consistent)
- Simplify associations - sweep complexity under the ‘?’
	○ GET /dogs?color=red&state=running&location=park
- Errors
	○ Errors become a key tool providing context and visibility into how to use an API.
	○ Use HTTP status codes
	○ Start by using the following 3 codes. If you need more, add them. But you shouldn't need to go beyond 8. 
		§ • 200 - OK 
		§ • 400 - Bad Request 
		§ • 500 - Internal Server Error
	○ Make messages returned in the payload as verbose as possible.
- Tips for versioning
	○ Never release an API without a version. 
	○ Make the version mandatory. Specify the version with a 'v' prefix. Move it all the way to the left in the URL so that it has the highest scope (e.g. /v1/dogs). 
	○ Use a simple ordinal number. Don't use the dot notation like v1.2 because it implies a granularity of versioning that doesn't work well with APIs--it's an interface not an implementation. Stick with v1, v2, and so on
	○ Maintain at least one version back.
	○ Should version and format be in URLs or headers?
		§ If it changes the logic you write to handle the response, put it in the URL so you can see it easily. 
		§ If it doesn't change the logic for each response, like OAuth information, put it in the header.
- Pagination and partial response
	○ Support partial response by adding optional fields in a comma delimited list. 
		§ /dogs?fields=name,color,location
	○ Use limit and offset to make it easy for developers to paginate objects.
		§ /dogs?limit=25&offset=50
- What about responses that don’t involve resources?
	○ when might not deal with a resource,
	○ Use verbs not nouns
		§ Calculate, Translate, Convert
		§ /convert?from=EUR&to=CNY&amount=100
- Supporting multiple formats
	○ /dogs/1234.json
	○ JSON is a good default format
- What about attribute names?
	○ Use JSON as default 
	○ Follow JavaScript conventions for naming attributes 
		§  Use medial capitalization (aka CamelCase) 
		§  Use uppercase or lowercase depending on type of object
- Tips for search
	○ using verbs not nouns when results don't return a resource from the database - rather the result is some action or calculation
		§ Global search: /search?q=fluffy+fur
		§ Scoped search: /owners/5678/dogs?q=fluffy+fur
		§ Formatted results: /search.xml?q=fluffy+fur
- Consolidate all API requests under one API subdomain.
	○ api.teachdogrest.com
	○ developers.yourtopleveldomain
		§ Web request, redirect from api.. to developers.. // developer... to developers...
- For specific scenrios, one may supress error code (example. Adobe)
	○ /public_timelines.json? suppress_response_codes=true 
		§ HTTP status code: 200 {"error":"Could not authenticate you."}
	○ Overall recommendations: 
		§ Use suppress_response_codes = true 
		§ The HTTP code is no longer just for the code
		§ Push any response code that we would have put in the HTTP response down into the response message
- API façade pattern
	○ Design the ideal API – design the URLs, request parameters and responses, payloads, headers, query parameters, and so on. The API design should be self-consistent. 
	○ Implement the design with data stubs. This allows application developers to use your API and give you feedback even before your API is connected to internal systems. 
	○ Mediate or integrate between the façade and the systems.