Referential Data

Convener

Jeff Jarchow (@thejarchow)

Attendees

• Jeff Pryeiak (@tsunllly)
• Ronisha Harvey (@ronisha_e)
• Calvin Bushor (@calvinbushar)
• Joe Colburn (@joetech)
• Joshua T Kalis (@kalisjoshua)
• Matthew Nagi (@pleonasm)
• Rob Chynoweth (@robertchynoweth)
• Manoj Agarwal (@wonderingmanoj)
• Lou Schilling (@lschill)
• Magnus Lassi (@magnuslassi)
• Nibras Hanna (@nibras85)
• Dmitri Skliarov (@dskliarov)
• Kevin Shamoun (@kevinshamoun)
• Dave Mehi (@davemehi)

Notes

• Discussion on the best practices of how to request API data from referenced tables, and how to format responses containing this data.

• From an API point of view, a separate resource can be created to supply different data. (e.g. one resource can be used to supply posts, while another resource can be used to supply posts with comments).

• Considerations should be taken when adding too many resources. It is general considered too many resources when there are multiple resources to provide the same data.

• When creating resources, take care in providing data in a way that doesn't expose the underlying storage means or relations of the data. In other words, use caution when exposing database foreign keys.

• If the need arises to provide relational data through foreign keys in a database, expose the actual data, not the foreign keys or the relationship of data.

• The general conses in the discussion was to alias, or map, the data in a way that may sense to the client, much like a normal view in a web app. (i.e. If a client app requests a customer list through the API, don't provide customer_type_id in the payload. It is better to display the actual customer type string in place of the customer_type_id.

• The client should never have to do implicit joins. This should be handled by the API.

• Persistent data != Exposed data

• There will always be two different schemas, the one you have for internal data storage and the one you expose to the customer.

• There needs to be a good balance between too much customization and pure resources that call thousands of hypermedia resources.

• There are great possibilities for client customization when it comes to APIs. For example, custom pages and reports can be achieved by allowing clients to specify limits and request specific data using custom URLs.

• General discussion proposes that the following API response samples (in JSON) should not be used so that underlying databases or model relations are not exposed. The response samples represent a single customer:

// First API Response:
{
  "customer": {
    "first_name": "Sample",
    "last_name": "Customer",
    "customer_status_id": "2"
  }
}

// Second API Response:
{
  "customer_status": {
    "id": "2",
    "title": "Inactive"
  }
}

-OR-

// All In One Nested API Response
{
  "customer": {
    "first_name": "Sample",
    "last_name": "Customer",
    "customer_status": {
      "id": "2",
      "title": "Inactive"
    }
  }
}

One should instead design the API with the client view in mind and respond in the following fashion:

// One Clear and Concise API Response
{
  "customer": {
    "first_name": "Sample",
    "last_name": "Customer",
    "customer_status": "Inactive"
  }
}

This type of response can reduce payload and/or reduce the number of API calls (depending on how the requests are performed), as well as provide the precise information needed by the client.

Additional Considerations (added later)