Requesting Data

OData services support requests for data via HTTP GET requests.

Requesting the Service Root

The request below returns a basic list of the resources available through the service. The response includes two types of links:

  1. The $metadata document that describes the schema of the service.
  2. Links to various collections of objects such as CUSTOMERS and ORDERS.

GET serviceRoot/

Response Payload

{
  "@odata.context": "serviceRoot/$metadata",
  "value": [
    {
      "name": "ABILITIES",
      "kind": "EntitySet",
      "url": "ABILITIES"
    },
  ...
    {
      "name": "CUSTOMERS",
      "kind": "EntitySet",
      "url": "CUSTOMERS"
    },
  ...
  {
      "name": "ORDERS",
      "kind": "EntitySet",
      "url": "ORDERS"
    },
  ...
  ]
}

Language

18.2

When working with a multi-lingual installation of Priority, you can specify which language to access the system by appending the appropriate language code to the service root URL, following the tabula.ini file name. This primarily affects the language used for error or warning messages returned from the system.

Example: https://www.example.com/odata/Priority/tabula.ini,3/test/CUSTOMERS('1234').

In this example, the system is being accessed in American English (language code 3). The Priority system manager can provide you with a list of language codes for the languages available in their particular system.

Requesting the Service Metadata

The request below returns the $metadata document for the service. This document contains a machine-readable description of the service model, including entities, type schemas, and properties.

Note: Just as a database schema implies nothing of the business significance of the entities that it represents, the business significance of the entities and properties is not documented here.

GET serviceRoot/$metadata

Response Payload

<?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 Namespace="Priority.OData" xmlns="http://docs.oasis-open.org/odata/ns/edm">
            <EntityType Name="ABILITIES">
                <Key>
                    <PropertyRef Name="ABILITYCODE" />
                </Key>
                <Property Name="ABILITYCODE" Type="Edm.String" MaxLength="3" />
                <Property Name="ABILITYDES" Type="Edm.String" MaxLength="32" />
                <Property Name="ABILITY" Type="Edm.Int64" />
                <NavigationProperty Name="ABILITYVALUES_SUBFORM" Type="Collection(Priority.OData.ABILITYVALUES)" ContainsTarget="true" />
            </EntityType>
      ...
      <EntityContainer Name="DefaultContainer">
                <EntitySet Name="ABILITIES" EntityType="Priority.OData.ABILITIES" />
                <EntitySet Name="ABILITYVALUECODES" EntityType="Priority.OData.ABILITYVALUECODES" />
                <EntitySet Name="ABSENTCHART" EntityType="Priority.OData.ABSENTCHART" />
                <EntitySet Name="ABSENTCODES" EntityType="Priority.OData.ABSENTCODES" />
        ...
        <EntitySet Name="pDOCSTATS" EntityType="Priority.OData.pDOCSTATS" />
            </EntityContainer>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

Every EntityType represented in the data model comprises a set of Properties and NavigationProperties. They map to the Priority entities as follows:

API Priority
EntityType Form
Property Field in a form
NavigationProperty Sub-form

Each Property can have one of the following types:

Knowing the type of each property is important when filtering or adding entities because the way the values are represented depends on the type. Here are examples of how values should be represented, depending on their type:

Edm.Decimal 42
Edm.Int64 42
Edm.String “A string”
Edm.DateTimeOffset 2017-04-16

Requesting Entity Collections

The request below returns the entity sets in the Part Families form, FAMILY_LOG.

GET serviceRoot/FAMILY_LOG

Response Payload

{
    "@odata.context": "serviceRoot/$metadata#FAMILY_LOG",
    "value": [
        {
            "FAMILYNAME": "0",
            "FAMILYDESC": "Default part family",
             ...
            "FAMILY": -1
        },
...
        {
            "FAMILYNAME": "001",
            "FAMILYDESC": "Sound Systems",
    ...
        }
        }
    ]
}

Requesting an Individual Entity by ID

To get a particular entity from a collection, append a key segment. Key segments in OData services are bound by parentheses because they may be composite keys, e.g., OrderLine(OrderID=1,LineNumber=1).

The request below returns an individual entity from the LOGPART form by the given PARTNAME “111-012”.

GET serviceRoot/LOGPART('111-012')

Response Payload

{
  "@odata.context": "serviceRoot/$metadata#LOGPART/$entity",
  "PARTNAME": "111-012",
  "BARCODE": "111-012",
  "PARTDES": "Panasonic Black Blu-ray Disc Theater SCBT100",
  ...
  "EXTPART": 29
}

To access related entities, keep appending segments that represent valid property names as defined in $metadata or in a full metadata response. For example, the request below starts at the service root and navigates to the entity set FAMILY_LOG, then to the resource keyed ‘001’, and finally to the FAMILY_LOGPART_SUBFORM property. Note that the @odata.context URL self-describes the payload.

GET serviceRoot/FAMILY_LOG('001')/FAMILY_LOGPART_SUBFORM

Response Payload

{
  "@odata.context": "serviceRoot/$metadata#FAMILY_LOG('001')/FAMILY_LOGPART_SUBFORM",
  "value": [
    {
      "PARTNAME": "111-001",
      "TYPE": "P",
      "PARTDES": "Sony HT7100DH Home Theater",
      "STATDES": "In Use",
      "PART": 18
    },
    {
      "PARTNAME": "111-002",
      "TYPE": "P",
      "PARTDES": "Sony HT-DDW790 Home-theater",
      "STATDES": "In Use",
      "PART": 19
    },
    {
      "PARTNAME": "111-003",
      "TYPE": "P",
      "PARTDES": "Samsung HT-AS720 Home Theater",
      "STATDES": "In Use",
      "PART": 20
    }
  ]
}

Requesting Text

Requesting text is similar to navigating to a related enity. The request below returns the text for the specified DOCUMENTS_D record:

GET serviceRoot/DOCUMENTS_D(DOCNO='SH17000001',TYPE='D')/DOCUMENTSTEXT_SUBFORM

Note: In this example, we use a composite key comprised of multiple properties. To specify a composite key, separate the different properties with a comma (,). The properties comprising the key for an entity can be found in the $metadata of the entity.

Response Payload

{
    "@odata.context": "serviceRoot/$metadata#DOCUMENTS_D(DOCNO='SH17000001',TYPE='D')/DOCUMENTSTEXT_SUBFORM",
    "value": [
        {
            "TEXT": "<style> p,div,li",
            "TEXTLINE": 1
        },
        {
            "TEXT": "{margin:0cm;font-size:10.0pt;font-family:'Arial';}</style><p",
            "TEXTLINE": 2
        },
        {
            "TEXT": "dir=rtl>",
            "TEXTLINE": 3
        },
        {
            "TEXT": "<p dir=\"rtl\" style=\"direction: ltr;\"><b><u>Delivery",
            "TEXTLINE": 4
        },
        {
            "TEXT": "instructions:</u></b></p><p dir=\"rtl\" style=\"direction:",
            "TEXTLINE": 5
        },
        {
            "TEXT": "ltr;\"><br></p><p dir=\"rtl\" style=\"direction: ltr;\">Each cake will be",
            "TEXTLINE": 6
        },
        {
            "TEXT": "delivered in separate packaging and refrigerated.</p>",
            "TEXTLINE": 7
        }
    ]
}

18.1

The OData service supports retrieving a record alongside its subform records in a single request, using the $expand system query option. The request below returns all ORDERITEMS_SUBFORM record for a specified ORDERS record:

GET serviceRoot/ORDERS('99100042')?$expand=ORDERITEMS_SUBFORM

Response Payload

{
  "@odata.context": "serviceRoot/$metadata#ORDERS/$entity",
  "CUSTNAME": "T000001",
  "CDES": "Joshua P. Atkins",
  ...
  "ORDERITEMS_SUBFORM@odata.context": "serviceRoot/$metadata#ORDERS('SO17000003')/ORDERITEMS_SUBFORM",
  "ORDERITEMS_SUBFORM": [
    {
      "PARTNAME": "TR0001",
      "PDES": "Almonds, mascarpone & strawberries tart",
      "TQUANT": 1,
      ...
    },
    {
      "PARTNAME": "FD0001",
      "PDES": "Phistacio Macrons with chocolate",
      "TQUANT": 1,
      ...
    }
  ]
}

Note: You can specify mutliple subforms to be returned in the $expand option:

GET serviceRoot/ORDERS('99100042')?$expand=ORDERITEMS_SUBFORM,ORDERSTEXT_SUBFORM

Requesting Full Metadata

By default, the OData service returns an extremely compact JSON format, by stripping out all the metadata that should be calculable by “smart” OData clients. For generic hypermedia clients, you can request additional metadata by using the Accept header, or $format system query option to request application/json;odata.metadata=full. The request below yields additional annotations in the payload, indicating type information and relationships to other resources.

GET serviceRoot/FAMILY_LOG?$format=application/json;odata.metadata=full

Response Payload

  {
  "@odata.context": "serviceRoot/$metadata#FAMILY_LOG",
  "value": [
    {
      "@odata.type": "#Priority.OData.FAMILY_LOG",
      "@odata.id": "serviceRoot/FAMILY_LOG('0')",
      "@odata.editLink": "FAMILY_LOG('0')",
      "FAMILYNAME": "0",
      "FAMILYDESC": "Default part family",
      ...
      "FAMILY@odata.type": "#Int64",
      "FAMILY": -1,
      "FAMILY_LOGPART_SUBFORM@odata.associationLink": "serviceRoot/FAMILY_LOG('0')/FAMILY_LOGPART_SUBFORM/$ref",
      "FAMILY_LOGPART_SUBFORM@odata.navigationLink": "serviceRoot/FAMILY_LOG('0')/FAMILY_LOGPART_SUBFORM",
      "FAMILYMALF_SUBFORM@odata.associationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYMALF_SUBFORM/$ref",
      "FAMILYMALF_SUBFORM@odata.navigationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYMALF_SUBFORM",
      "FAMILYSERVTYPES_SUBFORM@odata.associationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYSERVTYPES_SUBFORM/$ref",
      "FAMILYSERVTYPES_SUBFORM@odata.navigationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYSERVTYPES_SUBFORM",
      "FAMILYREQLABANALYSES_SUBFORM@odata.associationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYREQLABANALYSES_SUBFORM/$ref",
      "FAMILYREQLABANALYSES_SUBFORM@odata.navigationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYREQLABANALYSES_SUBFORM"
    },
    ......