Endpoints expose and customize Resources.
It’s important to remember that Resources themselves can operate completely independently of a request or response:
And Resources connect to other Resources. Our graph of data is defined outside of the actual API.
Endpoints expose this graph to the world. We might choose to have a
endpoint that can eager load comments (
?include=comments), but never expose
/comments directly. Or, we could do the opposite: expose lazy-loading
but disallow eager loading from
/employees. We can add caching rules,
or add an
/exemplary_employees endpoint with special query overrides.
Finally, Endpoints are in charge of the HTTP specification: request processing, response codes, caching, MIME types, and so on. If you’re thinking Rails, an Endpoint is the combination of a Route and Controller.
Often, you won’t need to customize Endpoints - especially if you’re using our Rails Resource generator. Endpoint logic mostly concerns:
- Side-effect behavior specific to the endpoint (e.g.: sending a
welcome email from
- Authorization (e.g
- Custom query parameter handling
- Validation handling
- Error handling
- Limiting Resource behavior
- Customizing Resource behavior
If your logic falls elsewhere, consider a Resource or Model.
1.2 Rails Integration
When using Rails, an endpoint is the combination of a Route and Controller:
You’ll note that Graphiti hooks into Rails with a mixin (set when using our application generator):
2 Customizing Resources
One common use case for endpoints is customizing the Resource base scope. This causes a new “starting point” for query building.
Consider the endpoints
/posts (basic CRUD) and
both are associated to PostResource,
/top_posts ensures that only
Posts with a certain number of upvotes get returned:
We’re able to reuse all the other logic in PostResource - relationships, filters, sorts, etc - while only returning “Top Posts”.
Resources define relationships to other resources. But we may not want all of those relationships exposed at a given endpoint.
Let’s say we’ve defined relationships:
Employee > Position > Department > Hardware > CostHistory
It’s reasonable to get an Employee, their Positions, and Departments for those positions in a single request. But is it really valid to also pull down all the hardware, as well as all the historical data on the cost of that hardware, in a single request? Allowing the entire graph to be pulled down in a single request can cause excessive load on our servers (and this is probably a better fit for lazy-loading via Links).
Let’s instead say that if we’re entering the graph at
furthest we can go is Department:
ETags are an important concept that is often overlooked. Etags tell browsers that the response to a GET request hasn’t changed since the last request and can be safely pulled from the browser cache. If you care about sparse fieldsets, you should care about ETags - if you’re limiting fields to reduce payload size, how about a payload size of zero?
It’s important to note that ETags are set by default in Rails, by checking the response body. This won’t prevent queries from executing, but it will save clients from downloading the response again if nothing has changed.
Let’s manually set an ETag:
From the documentation on #stale?:
In this case last_modified will be set by calling
maximum(:updated_at)on the collection (the timestamp of the most recently updated record) and the etag by passing the object itself.
Also consider the use case where data is ingested hourly. We can avoid a query altogether by checking when the last ingestion ran:
CAVEAT: When setting ETags, consider sideloads. In the above examples we are checking to see the last update of an Employee, but we may be sideloading (and filtering) Positions as well. Use custom endpoints or Sideload Allowlist to mitigate this issue.
If you have custom Endpoint logic, we suggest testing using an API Test.