Endpoints

Endpoints expose and customize Resources.

It’s important to remember that Resources themselves can operate completely independently of a request or response:

employees = EmployeeResource.all({
  filter: { title: 'engineer' },
  sort: '-created_at',
  page: { size: 10 },
  include: 'positions.department'
})

employees.map(&:first_name) # => ['Jane', 'John', ...]
employees.to_json # => { employees: [{ ... }] }

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 /employees endpoint that can eager load comments (?include=comments), but never expose /comments directly. Or, we could do the opposite: expose lazy-loading /comments, 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:

• Caching
• Side-effect behavior specific to the endpoint (e.g.: sending a welcome email from /users#create but not /admin/users#create)
• Authorization (e.g before_action)
• Custom query parameter handling
• Validation handling
• Error handling
• Limiting Resource behavior
• Customizing Resource behavior

If your logic falls elsewhere, consider a Resource or Model.

When using Rails, an endpoint is the combination of a Route and Controller:

# config/routes.rb
resources :posts, only: [:index]

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def index
    posts = PostResource.all(params)
    respond_with(posts)
  end
end

You’ll note that Graphiti hooks into Rails with a mixin (set when using our application generator):

class ApplicationController < ActionController::API
  include Graphiti::Rails

  # ... code ...
end

This gives us #sideload_allowlist and sets the context.

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 /top_posts. Though both are associated to PostResource, /top_posts ensures that only Posts with a certain number of upvotes get returned:

def index
  base_scope = Post.where("upvotes > ?", 100)
  posts = PostResource.all(params, base_scope)
  respond_with(posts)
end

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 /employees, the furthest we can go is Department:

class EmployeesController < ApplicationController
  self.sideload_allowlist = {
    index: { positions: 'department' }
  }

  # ... code ...
end

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:

def index
  posts = PostResource.all(params)

  if stale?(posts.data)
    respond_with(posts)
  end
end

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:

def index
  if stale?(EmployeeIngestion.last)
    employees = EmployeeResource.all(params)
    respond_with(employees)
  end
end

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.