abstract swish line in gradient colouring from pink to blue on a dark blue background

People First API usage guide

Response structure

JSON responses should be an object with at least one property of data or messages.

2xx responses MUST provide data and SHOULD provide meta, they MAY also provide a messages object.

4xx responses MUST provide a messages object. They SHOULD NOT provide a data block, they MAY provide a meta block where appropriate.

Data

The data block MUST contain exactly one property, the outer entity, this SHOULD match the type property of the resource.

There are two types of data that can sit inside this outer entity property, a single resource and a collection resource.

Collection

A collection response MUST be an array of resources. The resources SHOULD be the same shape but in some cases MAY be different shapes as long the type property is properly defined for each resource.

Resource structure

ID

A resource MUST have an ID that is exposed on the property id and uniquely identifies the resource.

Links

A resource MAY have a links object that sits on the property _links for collections this gives links that are specific to this item of the collection (as opposed to the collection as a whole which belong on the meta links). Please see meta links for information about the conventions around links blocks.

Type

A resource SHOULD define the type property, when defined this MUST be a string that uniquely represents this resource within the application. Consumers can use this to understand what resource shape they are looking at.

Property naming conventions

Resource properties MUST be camel case. Additionally, some types have specific suffixes which SHOULD be appended:

  • date: should be suffixed with Date
  • dateTime: should be suffixed with Id
  • relationships
    • one to one: should be suffixed with Id
    • one to many: should be suffixed with Ids

Property types

Properties MUST be exactly one of the following types:

  • string: represented in the data as using the double quotation marks ""
  • number: represented in the data as a number
  • boolean: represented as either true or false
  • date: represented using the ISO date format
  • datetime (point in time): represented as an ISO date time, the timezone MUST be provided as +0 - the consumer is responsible for localising this
  • datetime (relative): represented as an ISO datetime, the timezone MUST NOT be provided
  • relationships: see relationships

Relationships

Where a property describes a relationship (that is an ID for a separate resource) it SHOULD be suffixed with Id. These can either be one to one or one to many. Where it is one to one the value of the property MUST be an ID. Where the relationship is many to one this property MUST be an array of IDs. These IDs (where one to one or one to many) MUST come from the id property of one of the values object defined in the values meta which MUST be provided.

Nested resources

Resources MAY define a nested resource these however SHOULD be avoided. Where defined a nested resource MUST be an array of the resource to be nested, the property template link.


Meta

The meta tells the consumer information about the resource.

Property meta

The meta can describe the properties of the resource it does this by defining properties with the naming convention {outerEntity}.{propertyName}.

 {
  "data": {
    "employeeCompetency": {
      "id": "4251c9ab-c8d7-4a84-be84-166620859a30",
      "competencyNameId": ""
    }
  },
  "meta": {
    "employeeCompetency.id": {
      "hidden": true,
      "disabled": true
    },
    "employeeCompetency.competencyNameId": {
      "values": [],
      "mandatory": true
    },
    ...
  }
}


Disabled

The meta MAY define the disabled property, this MUST be a boolean or boolean expression. This indicates whether the property is read only.


Label

The meta for a property MAY define the label property. This MUST be a string which represents a human friendly label to be displayed to the end user for the related property.


Property links

A property meta MAY define a links object. Unlike the resource links this MUST come from the following list of possible links:

  • template: Used for nested resource to tell the consumer where the resource template for the nested resource can be fetched from
  • values: Used in conjunction with an empty values object, this tells the consumer where the options can be fetched from.


Hidden

The meta MAY define the hidden property, this MUST be a boolean or boolean expression. This tells the consumer whether the property should be shown to the end user.


Min length

The meta MAY define the minLength property, this MUST be a number and if defined MUST be describing a field which accepts a string value. This tells the consumer the minimum length the field can be in characters.


Max length

The meta MAY define the maxLength property, this MUST be a number and if defined MUST be describing a field which accepts a string value. This tells the consumer the maximum length (inclusive) the field can be in characters.


Mandatory

The meta MAY define the mandatory property, this MUST be a boolean or boolean expression. This indicates whether the associated property is a required field.

Mandatory means slightly different things for different property types:

  • boolean: Can not be null
  • string: Can not be null, also can not be an empty string
  • number: Can not be null


Redacted

The meta MAY define the redacted property, this MUST be a boolean or boolean expression. This indicates whether the associated property has had its value redacted.


Values

The resource MAY have relationships this is a foreign key relationship to another resource. Where a resource has a relationship it MUST define the values property. This MUST be an array of value objects (even if empty). The value object MUST define the id property and the value property. The value object MAY also define a links object behind the links property, this would usually only contain a self link to get the linked resource.

{
  "data": {
    "employeeCompetency": {
      "id": "4251c9ab-c8d7-4a84-be84-166620859a30",
      "competencyTypeId": "d1c3b192-db59-4d82-a9f9-a69500bf53a3",
      "competencyNameId": "",
      "evidenceIds": [
        "fa8e79cb-f82d-452f-91b2-a696008d471f"
      ],
      "competencyLevelId": "a438c6c3-4d41-450e-9440-157aea8e89b3"
    }
  },
  "meta": {
    "employeeCompetency.id": {
      "hidden": true,
      "disabled": true
    },
    "employeeCompetency.competencyLevelId": {
      "values": [
        {
          "id": "197ede52-c661-4f0f-8076-157aea8e89b0",
          "value": "Bad"
        },
        {
          "id": "6f1f506f-3af7-4f94-bc38-157aea8e89b1",
          "value": "Average"
        },
        {
          "id": "55b4a6a1-28e8-4f4c-b299-157aea8e89b2",
          "value": "Good"
        },
        {
          "id": "a438c6c3-4d41-450e-9440-157aea8e89b3",
          "value": "Excellent"
        }
      ]
    },
    "employeeCompetency.competencyTypeId": {
      "values": [
        {
          "id": "c1a06e23-c198-4814-b707-a69500bf53a3",
          "value": "Behavioral"
        },
        {
          "id": "d1c3b192-db59-4d82-a9f9-a69500bf53a3",
          "value": "Language"
        },
        {
          "id": "f02a6911-dc5c-4886-9afd-a69500bf53a3",
          "value": "Practical"
        }
      ]
    },
    "employeeCompetency.competencyNameId": {
      "values": []
    },
    "employeeCompetency.evidenceIds": {
      "values": [
        {
          "id": "fa8e79cb-f82d-452f-91b2-a696008d471f",
          "value": "PGCE (English)"
        }
      ],
      "links": {
        "values": {
          "href": "talent/employee/pt8e79cb-q82d-452r-91b2-a696008d471f/evidence"
        }
      }
    },
    "links": {
      "self": {
        "href": "talent/employee/fa8e79cb-f82d-452f-91b2-a696008d471f/competencies/229fa773-057d-4d84-90d3-1589b2ee8eb0?annotate=t"
      }
    }
  }
}


Property inheritance

Where an individual field has inheritance the response MUST contain an inheritance meta block on the property inheritance describing the inheritance see resource inheritance for the conventions of an inheritance block.


Links

The resource MUST have a links block under the meta. The links block is an object where each key is the name of a link. this MUST contain a self link and MAY contain others.

A link MUST contain the property href which is the link itself. The link MAY contain a params property, {TODO: WHAT IS THIS}? The link MAY also contain a meta property, this is a dictionary of values to describe meta about the resource behind the link.

The following links are well known links which MUST follow the definition where provided:

  • self: The self link is a link to get the resource the link is about (for a collection it is a link to get that collection, for a single item it is a link to fetch that single item)
  • first: Used in conjunction with pagination, a link to fetch the first page of results
  • last: Used in conjunction with pagination, a link to fetch the last page of results
  • prev: Used in conjunction with pagination, a link to the previous page of results
  • next: Used in conjunction with pagination, a link to the next page of results
  • create: Used on resource templates Tells the consumer where the resource should be posted to when creating.
  • {resourceName}Template: A link to get the template for the resource
{
  "data": {
    ...
  },
  "meta": {
    "links": {
      "self": {
        "href": "/api/personprofile"
      },
      "competencies": {
        "href": "/api/talent/competencies",
        "meta": {
          "count": 24
        }
      }
    }
  }
}


Resource inheritance

Where a resource has resource level inheritance. It MUST provide an inheritance property within the meta block which is an object. This object MUST provide a property state which describes the inheritance state of the resource. State must take one of the following values:

  • inherited: Inheriting from a parent
  • inheritable: Can reinherit (TODO: check this is correct?)
  • overridden: Overriding its inheritance
  • root: Root of an inheritance tree

The inheritance meta MAY also provide a link to fetch the inheritance path for this resource. Where provided this MUST be a link object on the property inhPath this link should be a resource where the inheritance tree can be fetched.


Pagination meta

When the resource is paginated the following meta MUST be provided in the meta block:

  • totalPages: the total number of pages in the set
  • pageNumber: the current page number
  • pageSize: the number of resources returned per page
  • maxPageSize: the maximum number of resources that can be requested on a page
  • count: the total number of resources in the set


Boolean expression

Meta data properties which are expected to provide a boolean MAY instead provide a boolean expression. This MUST be a javascript expression that evaluates down to a boolean. The expression MAY reference fields on the model using the format {outerEntity}.{propertyName}.

{
  "data": {
    "employeeCompetency": {
      "id": "4251c9ab-c8d7-4a84-be84-166620859a30",
      "name": "",
      "reason": "",
      "amount": 4,
      "target": 7,
      "completed": null
    }
  },
  "meta": {
    "employeeCompetency.id": {
      "hidden": true,
      "disabled": true
    },
    "employeeCompetency.name": {
      "mandatory": true
    },
    "employeeCompetency.reason": {
      "hidden": "employeeCompetency.name !== \"\""
    },
    "employeeCompetency.completed": {
      "mandatory": "employeeCompetency.amount >= employeeCompetency.target"
    },
    "links": {
      "self": {
        "href": "talent/employee/fa8e79cb-f82d-452f-91b2-a696008d471f/competencies/229fa773-057d-4d84-90d3-1589b2ee8eb0?annotate=t"
      }
    }
  }
}



Messages

The messages block is a way to convey information to the end user about the resource/request, where provided it MUST be an object on the property msg. This object MUST contain a key separating the different types, this key MUST have a value taking the form of an array of messages. The types MUST be one of:

  • error: Error messages, something went wrong
  • warning: Warning messages, nothing is wrong but there is something that requires the end user's attention
  • info: Information messages, messages for the end user with no further actions required

A messages object MUST have an id this is a unique code for the message. It MUST also have a text property, this is a string that provides a human friendly message explaining the message. Where the message pertains to a specific field the message SHOULD contain an objects property which is an array of strings which take the format {outerEntity}.{propertyName} to tell the user which property(ies) it references. In case the message refers to information or data existing in a different resource the message object SHOULD contain a values map with that information or data.

{
  "msg": {
    "error": [
      {
        "id": "0037INSVALIDFROM",
        "object": [
          "insurance.validFrom",
          "insurance.validTo"
        ],
        "text": "Insurance 'Valid from' must be before the 'Valid to' date"
      },
      {
        "id": "0056ATTACHTOOEARLY",
        "object": [
          "payslipItemPayrollAssociation.startDate"
        ],
        "text": "A payslip item cannot be attached to a payroll before the payroll start date",
        "values": {
          "payrollStartDate": "2020-10-10"
        }
      }
    ],
    "warning": [
      {
        "id": "0013NOPERSON",
        "text": "The person related to this record does not exist"
      }
    ],
    "info": [
      {
        "id": "0001SUCCESS",
        "text": "The data import session has started"
      }
    ]
  }
}

 

Looking for something specific?