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

Properties

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

Navigations properties have two types:

Collections

 <NavigationProperty Name="GENCUSTNOTES_SUBFORM" Type="Collection(Priority.OData.GENCUSTNOTES)" ContainsTarget="true" />

and non-collections

<NavigationProperty Name="SHIPTO2_SUBFORM" Type="Priority.OData.SHIPTO2" ContainsTarget="true" />

This distinction is important, as collections are represented as arrays, while non-collections are not.

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

‘20.0’

Requesting text is similar to requesting a related entity. The request below returns the text for order SO20000422.

GET serviceroot/ORDERS('SO20000422')/ORDERSTEXT_SUBFORM

The response contains a JSON object with the ODATA context, and the entirety of the HTML text as a string in the TEXT property. The other two properties are used when adding text

Response Payload

{
    "@odata.context": "https://dev.eshbel.com/odata/Priority/tabdev.ini/test/$metadata#ORDERS('SO20000422')/ORDERSTEXT_SUBFORM/$entity",
    "TEXT": "<style> p,div,li {margin:0cm;font-size:10.0pt;font-family:'Arial';}li > font > p {display: inline-block;}</style><p dir=rtl><font color=\"#0000ff\"><p dir=\"ltr\"><!--pdt-->06/04/20 14:00<!--edt--></p><p dir=\"ltr\">This is how the text looks like when retrieved by the REST API.&nbsp;</p><p dir=\"ltr\"><!--psi-->Sincerely,</p><p dir=\"ltr\">A Humble Documentarian</p><p dir=\"ltr\"></p><p dir=\"ltr\"><!--esi--></p></font><hr                 ss=\"\">&nbsp;<p dir=\"rtl\"><font color=\"#0000ff\"></font></p><p dir=\"rtl\" style=\"direction: ltr;\"><br></p> ",
    "APPEND": null,
    "SIGNATURE": null
}

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,
      ...
    }
  ]
}

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

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

You can use $expand to nest multiple levels of queries, retrieving information from a subform of a subform, or even deeper:

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

Response Payload

{
    "@odata.context": "https://www.eshbelsaas.com/ui/odata/Priority/tabmob.ini/usdemo/$metadata#ORDERS(ORDERITEMS_SUBFORM(ORDERITEMSTEXT_SUBFORM()))/$entity",
    "CUSTNAME": "0017F00002W6akoQ",
    "CDES": "marko enterprise",
    "CURDATE": "2020-06-22T00:00:00+03:00",
    "ORDNAME": "SO20000422",
    ...
    "ORDERITEMS_SUBFORM": [
        {
            "PARTNAME": "pt77",
            "PDES": "ptt77",
            ...
            "ORDERITEMSTEXT_SUBFORM": {
                "TEXT": "<style> p,div,li {margin:0cm;font-size:10.0pt;font-family:'Arial';}li > font > p {display: inline-block;}</style><p dir=rtl> <p dir=\"rtl\" style=\"direction: ltr;\">&nbsp;You reached this with multiple $expands, didn't you?</p> ",
                "APPEND": null,
                "SIGNATURE": null
            }
        }
    ]
}

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"
    },
    ......