Response serialization

Updated October 21, 2024

Responses to requests must be JSON formatted. To that end, we use JSONAPI::Serializer to consistently structure and serialize our endpoint responses. This adheres to the JSON API specification.

For example, here is a sample response body:

{
  "data": {
    "type": "phones",
    "id": "1"
    "attributes": {
      "number": "4445551212",
      "extension": "101",
      "country_code": "1"
    }
  }
}

Creating a Serializer

For information on creating a serializer visit the Serializer Docs: https://depo-platform-documentation.scrollhelp.site/developer-docs/how-to-create-a-serializer

Workflow

Our standard is for calls to any External Service Clients to return native Ruby objects. This allows new endpoints and integrations to utilize existing clients, and aids the testing process.

The conversion of these Ruby objects to a JSON response is done in the controller.

Here are a couple sample implementations:

# app/controllers/my_integration/facilities_controller.rb
#
module MyIntegration
  class FacilitiesController < ApplicationController
    def index
      facilities = facilities_service_client.for_user(current_user)

      render json: MyIntegration::FacilitySerializer.new(facilities)
    end

    def show
      facility = facilities_service_client.get(id: params[:id])

      render json: MyIntegration::FacilitySerializer.new(facility)
    end

    private

    def facilities_service_client
      MyIntegration::Facilities::Service.new
    end
  end
end

Limiting Serialized Data

Not all data returned by an External Service is necessary to include in an endpoint's response.

For instance, personally identifiable information (PII) can present security concerns. Making this data available may unnecessarily burden future auditing, in case of a breach.

Additionally, large lists of ancillary details increase the response size, and negatively impact performance.

For these reasons, be sure to only define attributes within the Serializer that are required for consumers.

Help and feedback

• Suggest content changes to this page.

• Submit new Platform Website content.

• Get help from the Platform Support Team in Slack.

• Submit a feature idea to the Platform.