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

OData Documentation

Introduction

The People First OData APIs are ideal for bulk data query operations, such as report generation. OData is a standard protocol that defines a RESTful API for consuming and querying data. As a RESTful API, it places very few technology constraints on how it can be accessed. It is supported natively by many third party products, such as Microsoft Excel and Microsoft Power BI. OData libraries are available for most popular programming languages. For detailed information and specifications regarding OData please refer to the OData site.

OData Support

While the OData protocol itself provides supports for data create, read, update, and delete operations, the People First OData APIs are designed specifically for data extraction purposes and is therefore read-only. The People First OData services support OData v4.0 and both JSON and XML response formats.

OData API Authentication

All OData API requests should be authenticated using an access token. For data tools that have native support for either HTTP Bearer, or Basic Authentication, you should follow the People First Access Token instructions here.

Where a data tool doesn't natively support Bearer or Basic Authentication, you might be able to configure a custom authentication mechanism within the tool. An example of creating a custom authentication configuration for tools using Microsoft Power Query (e.g. Excel and Power BI) can be found here.

API Compatibility Considerations

As with the other People First APIs, consumers of the OData APIs will need to be aware of the type of changes that are considered to be backwards compatible, and will need to code their applications to handle them. Further details are available here.
 

Data API Discovery

OData aims to provide a self-describing data model and API for accessing that data model. This allows generic clients to interact with an OData service by discovering its data API using well defined mechanisms. The starting point for accessing any OData service is the service root URI.

All OData services publish a service document resource. The service document lists all of the resources (entity sets, functions, singletons) that are available from the service. The service document resource can be retrieved by issuing a GET request to the service root URI.

In addition, an OData service will publish a metadata document resource. The metadata document lists all of the data types, sets, functions, and actions understood by the service. This allows you to understand the entities (resources) that the service exposes and how to interact with them. The metadata document resource can be retrieved by issuing a GET request to the URI obtained by appending /$metadata to the service root URI.

The following examples show the relationship between the discovery URIs:

  • Service Root - https://mydomain.com/myservice/odata
  • Service Document - https://mydomain.com/myservice/odata
  • Metadata Document - https://mydomain.com/myservice/odata/$metadata
     

Below is a snippet from a typical service document:

{
  "@odata.context": "https://mydomain.com/myservice/odata/$metadata",
  "value": [
    {
      "name": "applicationstates",
      "url": "applicationstates"
    },
    {
      "name": "applications",
      "url": "applications"
    },
    {
      "name": "applicants",
      "url": "applicants"
    }
  ]
}

 

The above service document describes an OData service that exposes three entity set resources, namely applicants, applications, and applicationstates. The service document also provides a link to the metadata document describing those resources.
 

Below is a snippet from a typical metadata document:


  <?xml version='1.0' encoding='UTF-8'?>
  <edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
      <edmx:DataServices>
          <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="MyService">
              <EntityType Name="applicant">
                  <Key>
                      <PropertyRef Name="Id"/>
                  </Key>
                  <Property Name="Forename" Type="Edm.String" MaxLength="255"/>
                  <Property Name="Surname" Type="Edm.String" MaxLength="255"/>
                  <Property Name="Id" Type="Edm.Guid"/>
                  <NavigationProperty Name="Applications" Type="Collection(MyService.application)" Partner="Applicant">
                      <ReferentialConstraint Property="Id" ReferencedProperty="Applicantid"/>
                  </NavigationProperty>
              </EntityType>
              <EntityType Name="application">
                  <Key>
                      <PropertyRef Name="Id"/>
                  </Key>
                  <Property Name="Id" Type="Edm.Guid"/>
                  <Property Name="CurrentStateId" Type="Edm.Guid"/>
                  <Property Name="Applicantid" Type="Edm.Guid"/>
                  <NavigationProperty Name="CurrentState" Type="MyService.applicationstate">
                      <ReferentialConstraint Property="CurrentStateId" ReferencedProperty="Id"/>
                  </NavigationProperty>
                  <NavigationProperty Name="Applicant" Type="MyService.applicant" Partner="Applications">
                      <ReferentialConstraint Property="Applicantid" ReferencedProperty="Id"/>
                  </NavigationProperty>
              </EntityType>
              <EntityType Name="applicationstate">
                  <Key>
                      <PropertyRef Name="Id"/>
                  </Key>
                  <Property Name="CurrentStage" Type="Edm.String" MaxLength="255"/>
                  <Property Name="Id" Type="Edm.Guid"/>
                  <Property Name="CreationDate" Type="Edm.DateTimeOffset" Precision="3"/>
                  <Property Name="ApplicationId" Type="Edm.Guid"/>
                  <Property Name="CurrentStageDescription" Type="Edm.String" MaxLength="255"/>
                  <Property Name="NextStage" Type="Edm.String" MaxLength="255"/>
                  <NavigationProperty Name="Application" Type="MyService.application">
                      <ReferentialConstraint Property="ApplicationId" ReferencedProperty="Id"/>
                  </NavigationProperty>
              </EntityType>
              <EntityContainer Name="MyServiceContainer">
                  <EntitySet Name="applicationstates" EntityType="MyService.applicationstate">
                      <NavigationPropertyBinding Path="Application" Target="applications"/>
                  </EntitySet>
                  <EntitySet Name="applications" EntityType="MyService.application">
                      <NavigationPropertyBinding Path="CurrentState" Target="applicationstates"/>
                      <NavigationPropertyBinding Path="Applicant" Target="applicants"/>
                  </EntitySet>
                  <EntitySet Name="applicants" EntityType="MyService.applicant">
                      <NavigationPropertyBinding Path="Applications" Target="applications"/>
                  </EntitySet>
              </EntityContainer>
          </Schema>
      </edmx:DataServices>
  </edmx:Edmx>

 

The above metadata document describes the types that are contained within the entity sets that the service exposes e.g. the applicants entity set is comprised of MyService.applicant entities.

The document also defines the data model for each of those entities e.g. MyService.applicant has an Id, Forename, Surname, and navigable collection of applications (MyService.application).

Looking for something specific?