...
- these conventions are derived from a very useful set defined by Apigee: http://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf.
- the initial discussions about APIs were captured in API Thoughts.
- Django REST Framework version 2 documentation (we are currently using version 2.3.14, which has different APIs from the version 3).
- read up on our existing APIs: http://edx-platform-api.readthedocs.org/en/latest/
- for comparison, it is worth studying public API documentation from the big internet companies
High Level Requirements
- Consumer-Perspective. Design your API from the perspective of the consumer, NOT the perspective of your underlying implementation. For example:
- If the underlying implementation requires accessing multiple models or multiple apps/projects, this does not need to be reflected in a public interface. From the perspective of the consumer, it's simply one thing they are requesting.
- Keep CRUD operations together within its corresponding resource. Why have the client go to one resource to read it and then another resource to write it?
- Simple. Keep the top-leveI resources clear and simple - focusing on what the client is looking to consume. You can hide complexity within the parameters.
- Discoverability. Support HATEOAS where possible. This allows us to change our URLs without needing to worry about updating the mobile apps if the app discovers its URLs from a base URL.
- Separation of concerns. Do not require the consumer to know any implementation details. For example, an API shouldn't require the client to know the inter-dependencies of fields. Rather, all such business rules should be owned by the server. This allows the client to be lightweight and easily maintainable in the future.Conservative Publishing. Keep your just implemented endpoint "private" until it has been field tested for a few months before you publish it to read-the-docs. Once published, while you may have a deprecation strategy, you have committed to support that endpoint indefinitely for the foreseeable future - especially if it's used by mobile clients or external partners
- Explicit Support Levels. APIs should make it clear whether they are experimental or more permanent as a part of their documentation.
Discoverability. Support HATEOAS where possible. This allows us to change our URLs without needing to worry about updating the mobile apps if the app discovers its URLs from a base URL.
Conventions
1. URL Naming
Must: Keep your base URL simple and intuitive.
Suggestion: Follow this basic URL structure if you are concerned about collisions within your service. By "collisions", we mean TBD.
No Format /api/{API_NAME}/{VERSION}/...If collisions are not a concern (for example, when exposing APIs from context-specific IDAs), then you can eliminate the use of API_NAME.
No Format /api/{VERSION}/...
Must: Keep the API name flat. Use two base URLs per resource: collection/identifier, e.g.
No Format /api/user/v1/accounts/{USERNAME}- It is not necessary that there is a one-to-one correspondence between an API and the Django app that provides it. In fact, which Django app implements an API is an implementation detail and need not be bound to a public interface.
...