This will be an adventure in navigating a Hypermedia API. This API will illustrate API standards that should be followed in all APIs.
- Where to begin?
GET /- (non-authenticated)
- Perform a simple GET request to get a list of available API resources.
- This resource will always be available - authenticated or not - and will always return a resource. The resource returned will also optionally include links to resources that are available. Following links is what the web is ALL about. There are different types of links: resources, informational (status), meta (schema), etc.
- [Next Step]
- Create a session token to make authenticated requests:
POST /session-tokens
- Start a session.
POST /session-tokens- (non-authenticated)
- Now that you have a session token you will be able to make authenticated requests to the API which means more resources will be available to you.
- [Next Step]
- Make your original request; using HTTP Basic Authorization (header)
GET /Authorization: Basic <session-token>
- A new beginning.
GET /- Great! You've made your first authenticated request to this API. HTTP Basic auth is hardly the most secure but it will suffice for our needs. Continue supplying this HTTP header for all requests going forward.
- A new link is available to you now, identified by the link relation (rel) "collection". Don't worry about the URL, it's randomized so it is only available to you and will only be usable once.
- [Next Step]
- Follow the link for the the "collection".
- What's available now?
GET /<adjective>-<noun>s- RESTful APIs have two types of resources and the first of those is the collection type; which is what this is. Collections are groups of like resources. Collections have some meta-functionality to make them more accessible, such functionality are: paging and filtering.