1. questions to answer
1.1. how do you approach deciding what an API contains
1.2. what are some examples of good API’s?
1.2.1. amazon
2. implementations
2.1. http://clojure-liberator.github.io/liberator/tutorial/decision-graph.html
3. resources
3.1. How to Design a Good API and Why it Matters (Josh Bloch) (1)
3.1.1. what makes an API “good"
3.1.1.1. (1)
3.1.1.1.1. Easy to learn
3.1.1.1.2. Easy to use, even without documentation
3.1.1.1.3. Hard to misuse
3.1.1.1.4. Easy to read and maintain code that uses it
3.1.1.1.5. Sufficiently powerful to satisfy requirements
3.1.1.1.6. Easy to extend
3.1.1.1.7. Appropriate to audience
3.1.2. what are general principles to go by
3.1.2.1. (1)
3.1.2.1.1. API Should Do One Thing and Do it Well
3.1.2.1.2. API Should Be As Small As Possible But No Smaller
3.1.2.1.3. Implementation Should Not Impact API
3.1.2.1.4. Names Matter–API is a Little Language
3.1.2.1.5. Documentation Matters
3.1.2.1.6. Don't Violate the Principle of Least Astonishment
3.2. https://mathieu.fenniak.net/the-api-checklist/
3.2.1. http API's should conform to HTTP semantics
3.2.2. some other useful stuff in that
3.2.2.1. like version or timestamp your paginations, to avoid showing stuff more than once
3.3. http://en.wikipedia.org/wiki/Data_transfer_object
3.3.1. http://martinfowler.com/eaaCatalog/dataTransferObject.html
3.3.1.1. minimization of method calls (especially over http!) is a goal
3.3.1.1.1. An object that carries data between processes in order to reduce the number of method calls.
3.3.1.2. formal Objects vs. Ruby hashes
3.3.1.3. find some Amazon API docs as an example
3.3.2. http://programmers.stackexchange.com/a/171479
3.3.2.1. So, if multiple requests are required to bring data for a particular task, data to be brought can be combined in a DTO so that only one request can bring all the required data.
3.3.2.2. same can be applied to service calls that need to atomically update multiple values -- can do that via a single succeed/fail call
3.3.2.2.1. else you have to co-ordinate stuff on the client, and the client has to hold more context and logic on its side
3.3.3. DTO's IRL
3.3.3.1. intermediary documents
3.3.3.1.1. a dry cleaning slip
3.3.3.1.2. a purchase order
3.3.3.1.3. an order for a meal
3.4. http://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling
3.4.1. "A resource is a conceptual mapping to a set of entities" -- Fielding
3.4.2. It is very important to select the right resources and model the resources at the right granularity while designing the REST API so that the API consumers get the desired functionality from the APIs, the APIs behave correctly and the APIs are maintainable.
3.4.2.1. 1:1 mapping from db table to resource can be an impeding oversimplifictaion
3.4.3. judicious modeling of resources
3.4.4. avoiding chattiness and http latency issues due to being too fine-grained in CRUD txns
3.4.5. Preventing migration of business logic to API consumer
3.4.5.1. Unit of Work!
3.4.5.2. that whole section is spot-on
3.4.6. for complex business processes spanning multiple resources, we can consider the business process as a resource itself
3.4.7. It is very important to distinguish between resources in REST API and domain entities in a domain driven design. Domain driven design applies to the implementation side of things (including API implementation) while resources in REST API drive the API design and contract. API resource selection should not depend on the underlying domain implementation details.
3.4.8. In a world of four-verb (AtomPub-style) CRUD, it's as if you allow random external parties to mess around with your resource state, through PUT and DELETE, as if the service were just a low-level database. PUT puts too much internal domain knowledge into the client.
3.4.9. If we go with this CRUD API design, the business meaningful event data such as when was the address changed, who changed it (changed by customer or by the bank staff), what was the change, history of changes, etc. will get missed out. In other words, we will miss out the business relevant event data that may be useful at a later stage. Also, with this approach, the client code needs to have the knowledge of “Customer” domain (including Customer’s attributes, etc.).
3.4.10. Thinking about the paper form analogy in a typical business function helps us to focus on the business requirements in a technology agnostic way as discussed by Dan North in his article “A Classic Introduction to SOA”.
3.4.11. Perhaps this can be a rule of thumb: Does the process need state of its own? Will the business be asking questions about this process such as - what is the status of the process? if it failed, why? Who initiated it and from where? how many of them happened? What are the most common reasons for failure of the process, and at which step? How long did it take on average, min, max? For most non-trivial processes, businesses want answers to these questions. And such a process should be modeled as a resource in its own right.
3.4.12. still assumes working within the realm of resources
3.4.13. http://www.thoughtworks.com/radar/techniques/rest-without-put
3.4.14. http://martinfowler.com/eaaDev/EventSourcing.html
3.4.15. http://martinfowler.com/bliki/CQRS.html
3.4.16. In summary, PUT puts too much internal domain knowledge into the client as discussed earlier. The client shouldn't be manipulating internal representation; it should be a source of user intent. On the other hand, PUT is easier to implement for many simple situations and has good support in libraries. So, the decision needs to be balanced between simplicity of using PUT versus the relevance of event data for the business.
3.4.17. github examples
3.4.18. course grained, command oriented and fine-grained wrapper-around-data approaches can be used together
3.4.18.1. "can you bring some salt"
3.5. https://github.com/ServiceStack/ServiceStack/wiki/Advantages-of-message-based-web-services
3.5.1. !!
3.5.2. the mount volume example
3.5.2.1. vs. its restful equivalent
3.5.2.2. and leaking details
3.5.2.2.1. and not hiding implementation
3.5.2.3. and having a shallow name space
3.5.3. their amazon examples are good
3.5.4. this whole framework is pretty amazing
3.5.5. clearly states the benefits of a DTO-based request/response approach
3.6. http://thenextweb.com/dd/2013/12/17/future-api-design-orchestration-layer/
3.6.1. This is achieved by breaking down the resource-based APIs and allowing them to be queried against like a database through flexible parameters and payloads that can contract, expand and possibly morph based on what is needed. The benefit here is that once the query language is set, the API team does not need to keep writing wrappers as new implementations are needed for different devices.
3.6.2. The detriment, however, is that the query-based API is still a set of rules to which the developer needs to adhere, although these rules are much more flexible than the resource-based API model.
3.6.3. orchestration layer
3.7. http://www.servicedesignpatterns.com/WebServiceAPIStyles
3.7.1. useful, but not sure how it fits into the larger discussion
3.8. http://dannorth.net/classic-soa/
3.8.1. great stuff
3.9. http://thenextweb.com/entrepreneur/2013/09/15/why-you-probably-dont-need-an-api-strategy/
3.9.1. key to api success is to know your audience (client developers) and how best to serve them
4. fielding
4.1. REST is data-oriented RPC, as practiced by many
4.2. really, data-oriented RPC with sparse business process intelligence, relegating the service to being a database CRUD service tightly bound to the implementation details, etc.
5. more stuff
5.1. whereas API's like Amazon's use Data Transfer Objects and have a very flat namespace, as opposed to deeply nested resources, which tightly bind implementation to interface. So that if any one thing about the hierarchy of resources changes, everything is broken.
5.2. random
5.2.1. schemas
5.2.1.1. json and types
5.3. so, use hierarchies of resources for a query-able (sorting and filtering and paging) read-only view of the data
5.3.1. still cumbersome though, as opposed to constructing a query DTO and retrieving results as specified in the query
5.4. recognize that 'resources' can be abstract and not necessarily tied to the actual structure of the underlying system and its data
5.5. use DTO's as work tickets and ways of requesting "action" by the API
5.6. defining a service in terms of commands, or service requests
5.7. DTO-focused request/response objects can be used as an adjunct to REST, or DTO's via command/event BP objects modeled as resources
5.8. terseness and efficiency of communication as design goals for an API
5.8.1. two wiz wit
5.9. query languages that aggregate data across services
5.9.1. exist in java app servers
5.9.2. business process collaboaration, and such
5.9.3. BPQL?
6. documents about web api design
6.1. conflate api design and rest as a given
6.2. rest is an entities-first data-driven, not process-driven, approach to modeling client interactions
6.3. as such it has limitations
6.4. you need to know when to augment your domain models representation as resources
6.4.1. to include business process resources
6.4.1.1. and the data about them
6.4.1.1.1. like a lunch ticket
6.5. and when a flatter DTO-focused request/response data structure-oriented approach is more advantageous
6.6. and control the flow of changes
7. filtering
7.1. cqrs
7.2. filtering rest api
7.2.1. http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#advanced-queries
7.2.2. use post to create named query per user, then get on query results
7.2.2.1. http://stackoverflow.com/questions/14992293/providing-complex-filtering-rest-api
7.2.2.2. and have named queries that are universal
7.2.3. http://stackoverflow.com/questions/13110147/rest-and-complex-search-queries/13120708#13120708
7.2.3.1. http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
7.2.4. https://developers.google.com/ad-exchange/seller-rest/filters
7.2.5. http://www.magentocommerce.com/api/rest/get_filters.html
7.2.6. ql.io, JSONQuery, etc.