Media Operations Platform REST API Reference - 10.4

Summary

This document describes the Xytech Media Operations Platform implementation of a Representational State Transfer (REST) service interface, and it provides information on the operations available through the REST-based application programming interface (API).

Scope

This document describes the Media Operations Platform REST API only, which is the interface by which a third-party component can make REST calls over HTTP to the Platform application server endpoint and receive responses from it. It does not cover any of the following topics:

• Web Hooks – please refer to the following article called Webhooks user guide 10.4. 
• The Platform SOAP API
• Platform Service Order Adapters
• Other outbound interfaces, such as alternate authentication systems.
  Although most of this document is relevant to the v1 API, it also includes features that only exist in the v2 API and are primarily intended for users of the v2 API.

Definitions

Background and Concepts

This section describes the fundamental ideas behind APIs, the REST protocol, and the portions of the Platform system involved with

API Basics

The purpose of an application program interface (API) is to allow an external computer or piece of software (here called an endpoint) to interact with the system that exposes the interface (here called the host), to allow the endpoint to do one or more of the following:

• Create new records in the host system
• Retrieve information from the host system
• Update existing records in the host system
• Delete existing records in the host system
• Trigger operations or business logic in the host system

Unlike a user interface, an API is a mechanism for one piece of software to talk to another and usually does not require the action of a person. In some cases, however, an API is used to allow a third-party user interface to interact with the host system.

REST Basics

Representational State Transfer (REST) is an architectural style of principles that define a set of constraints for how two systems can communicate over a network such as the World Wide Web. These principles are used to create reliable Web APIs where no state information needs to be retained by the host system offering the API.

Features and Benefits

The REST architecture provides the following benefits:

• • Simple – In general, REST calls follow a set of common patterns that can be learned and followed without significant amounts of special syntax.
  • Stateless - Being “stateless” allows the API provider to handle high volumes of requests with high performance.
    • The server is not required to keep state information in memory.
    • The client is not required to connect to a specific server to utilize stored state information, so requests can be distributed among any number of servers.

HTTP Methods

RESTful services utilize HTTP methods to differentiate between different types of API calls.

Response Codes

REST services are built on top of the HTTP protocol, so calls to the REST service generate HTTP response codes. In many cases, the HTTP response code will be accompanied by additional information in the header or body of the message. In some cases, the HTTP response code may be the only response.

For more information refer to the appropriate section of the HTTP protocol or a developer resource for HTTP status codes, such as the MDN Web Docs.

Xytech Platform REST API Basics

The Platform is, at a fundamental level, a system that deals with creating, updating, and utilizing a particular type of object referred to as a document.

• Each Platform document is a representation of a database table or collection of database tables.
  • Each document has a primary table and may have one or more sub-tables.
  • All sub-tables are children of the primary table, and a sub-table can have one or more child sub-tables.
• Each document is one of the following types of documents:
  • Setup - generally describes a single item, and usually only contains a primary table. Setup documents are often used to manage simple items used to generate lists of options in other documents, such as status labels or predefined sets of codes.
  • Maintenance – generally describes either master data (which are used in transactional data) or transactional data. Maintenance documents often contain one or more sub-tables.
  • List documents provide access to sets of other records, such as Setup and Maintenance documents.

The Platform REST API is JSON-based and has Open API v3.0 API specifications for each API call available in YAML. These specifications can be retrieved as a plain YAML file and are also readily available to be viewed in a browser through the Swagger UI. See the Error! Reference source not found. below for more information.

REST API v1 and v2

Deprecation of v1 API

• REST API v1 was the first Xytech REST API product. It had limitations that required breaking changes to improve so v2 was made available from Xytech v9.4 release with improved functionality.
• REST API v1 will no longer be supported in version 11.0 and beyond.
• All new integrations should use v2 API and existing integrations should port to v2
• To use v2 API, change the base URL version number from ../v1/.. to ../v2/..

Additional Features in v2 API (as of Platform v10.2 release)

• Payload structure updated to be more robust and scalable.
  The document name is now always added as the root element of the payload with an array containing the details.
  Example showing the additional root element jm_job:
  

  API V1 JSON payload for GET JmJob

  API V2 JSON payload for GET JmJob

  /JmJob/job_no=11261 {     "other_cust_id": "01234",     "customer_name": "Productions",     "phone_user_1": null,     "phone_user_2": null,     "phone_user_3": null,     "phone_department": null,     "phone_city": "London",     "phone_job_title": null,     "job_desc": "Job",     "title": null,     "contact": "Emma",     "phone_number": "34567890",     "po": null,     "account_rep_no_2": null,     "due_date": "2024-05-24T06:00:00",     "flat_bid": "N",     "flat_bid_amount": 0.0,     "flat_bill_amount": 0.0,     "job_discount": 0.0,     "agency_list_id": null,     "agency_name": null,

  /JmJob/job_no=11261       "jm_job": [         {             "job_no": {                 "job_no": 11261,                 "external_key": null             },             "division_no": {                 "division_no": 101,                 "division_desc": "XUK Division",                 "division_code": "XUK",                 "external_key": null             },             "cust_id": {                 "list_id": "1720",                 "other_cust_id": "01234",                 "cust_reference": null,                 "external_key": null,                 "cust_id": "1720"             },             "other_cust_id": "01234",             "customer_name": "Productions",             "phone_user_1": null,

  
  See the Swagger documentation for the JSON structure of the endpoint you are interested in.

• Additional PATCH capabilities
  In addition to the existing v1 PATCH method where each changed field must be defined using the operation/path/value payload structure:

[

You can now use the same JSON payload you would use for a POST call to update a record. This needs to use the header 'Content-Type: application/json-patch+json'. See the section below for more details.

• Pagination & sorting
  API Pagination has been added to the REST API ‘Get’ Query for Lists.
  Parameters for:

  pageSize	are the number of records returned per page.
  page	are the page number to return.
  sort	is the field to sort by followed by ascending or descending order.

  Example:
  To return the first 10 records on page 1 sorted by product_no:
  GET
  {server}}/JmOrgProductList?query="active":"Y"}&resultColumns="L":"product_no","product_desc"]}&sort="product_no_desc"]&pageSize=10&page=1
  
  This will allow sites to call for data in manageable payloads without exceeding memory limitations.

Running and Connecting to the REST API

Licensing

While there is a specific license point for the REST API, by default all Platform installations are given access to the API.

Installing and Configuring

The REST API is a component of the Platform’s Application Server. On hosted systems, it is available by default to all customers.

Instance Information You Will Need

To be able to connect with the REST API, you will need to know the instance:

• Base URL (including a port number for the API) e.g. ‘https://example.com:11001’
• Database name e.g. ‘DEMO1’

If you do not have this information, please contact Xytech Technical Support.

Swagger API Documentation

From Platform version v10.2, a Swagger index page has been introduced to assist in the navigation and creation of Swagger YAML documentation. The Swagger index page can be found by entering the base URL for your instance and adding “/ApiDocs” to the end (e.g., www.xytechexample.com/ApiDocs). The Xytech API Index page is displayed. 

Using the Index
The Index is comprised of the following areas:

• Version: Displayed in the upper left corner of the screen. This shows the API version, currently either v1 or v2.
• Selected Database: The name of the database currently selected for this host.
  Only modules for that database are shown.
• Available Databases: (Where multiple databases exist on the same host) Click a database to select it and view its associated modules.
• Filter Documents: Enter text into this field and press [Enter] to only display matching document descriptions. To clear the filter, delete the text and press [Enter].
• Module and Document List: Only modules in the selected database are displayed. Click any Module to expand and show the documents it contains. Each document has a label that describes its type (Document [maintenance], List, or Setup).

For versions earlier than v10.2, you will need to generate the Swagger documentation manually for each document endpoint.

Use a browser to generate the Swagger document:

http://{host}:{port}/API/v2/database/{db_name}/spec/{docName}

For example:

http://myhost:8088/API/v2/database/mp10/spec/JmJob

The above URL will generate the Swagger document and then display the Swagger document.

To display generated Swagger documents, browse to:

http://{host}:{port}/REST/SwaggerUI/dist/index.html?document={docName}_v2

For example:

http://myhost:8088/REST/SwaggerUI/dist/index.html?document=JmDivision_v2

Authentication

The REST API currently uses Basic Authentication and will require a database login account.
Always use HTTPS encrypted protocol when communicating with the REST API to ensure credentials are not passed in clear text.

Using Postman as a Client

This section describes using the third-party Postman application as an API client for testing and troubleshooting purposes. The example uses the JmJob (Job) endpoint.
To execute a GET call to retrieve an existing record:

1. Open the Postman application
2. From File click New and click HTTP Request
3. Leave the method as GET
4. Enter the URL:
   
   
   • http://{APIbaseURL}/API/v2/database/{dbname}/jmJob/job_no=100 
     • Replace {base_url} & {dbname} with your base URL & database name and provide a valid Job Number that exists in your instance.
5. On the Authorization tab, set Type to Basic Auth and enter a valid username and password, e.g. xytech/xytechpw
6. Click Send and observe the response.

To execute a POST call to create a new record: 

1. Open the Postman application.
2. From File click New and click HTTP Request.
3. Change the method to POST.
4. Add a Header:
   • Key: Content-Type
   • Value: application/json
5. Enter the URL: http://{APIbaseURL}/API/v2/database/{dbname}/jmJob
6. On the Authorization tab, set Type to Basic Auth and enter a valid username and password, e.g. xytech/xytechpw
7. On the Body tab,
   • set the type to json, and provide a valid JSON object with the minimum fields to create a job. For example, to create a simple Job:

   {

     "jm_job": [
           {
               "job_no": {
                   "job_no": 345
               },
               "job_desc":"Leaves of October",
               "job_type_no": {
                   "job_type_no": 7
               },
               "po": "PO1234",
               "job_reference": "Streets Ahead"
           }
       ]
   }'
   NOTE: to generate the primary key job_no, set the value to -1.
   When creating multiple sub-records in a single call, subsequent records must advance the primary key ID by -1. E.g -1, -2, -3 etc…
8. Click Send and observe the response.

To execute a DELETE call to remove an existing record:

1. Open the Postman application.
2. From File click New and click HTTP Request.
3. Change the method to DELETE.
4. Enter the URL:
   http://{APIbaseURL}/api/v2/database/{dbname}/JmJob/job_no=67982
5. On the Authorization tab, set Type to Basic Auth and enter a valid username and password, e.g. xytech/xytechpw
6. Click Send and observe the response.

Using cURL as a Client

This section describes using the third-party cURL command line utility as an API client for testing and troubleshooting purposes.

Many REST clients (either via an online tool or desktop application) use a lightweight program called curl to interact over many different types of network protocols (including HTTP, HTTPS, FTP, IMAP, etc.) Windows users may use the curl command in Command Prompt (C:\Windows\System32\cmd.exe) to fire up quick information dumps of useful data.

For example:

curl --user xytech:xytechpw -X GET
"http://{APIbaseURL}/api/v2/database/{dbname}/JmJob/job_no=67982" -H"accept: application/json" > U:\rest_api_hit.txt

Example Platform REST API calls

An extensive set of example API calls is available via the Platform’s REST API Postman Collection. This collection contains example calls for three types of documents (maintenance, list, and setup). The Start-up Guide and Postman Collection are available upon request.

GET Query Parameters

GET calls for list documents support two additional parameters for executing queries, the "query" parameter and the "resultColumns" parameter. Each has a specific syntax and usage, described below.

“query” Parameter

This section describes the syntax and options used for the query parameter sent to the Platform REST API in GET commands for list documents.
In GET commands, the Query parameter determines the criteria used to retrieve records. Like other parameters, the criteria are included in the URL of the GET call in JSON format.
For example:

http://{APIbaseURL}/documentList?query={key: value}

Such as:

http://{APIbaseURL}/jmJobList?query={"job_no": "12345"}

Note: The query parameter is supported only for GET requests for List-type documents and is not supported by GET requests for Setup or Maintenance documents. For each field in the criteria, there are different ways to supply the value. The simplest is a single string or number, but other options provide additional capabilities. In these examples, the docURL is assumed to include the APIbaseURL and the document endpoint, e.g. ‘https://example.com:11001/JmJobList’

• String or Number

• Range

• In (Set)

• Null / Empty

• NE (Not Equal)

NULL Values

The Null parameter returns any record that has a null value for the specified key, which indicates that no value has ever been set. This differentiates it from an empty string for text-based or date-based properties, a 0 value for numbers, and true or false values for Boolean properties.

Note: Not all properties support null values. If possible, check whether the database column in the appropriate column allows nulls.

Keys are strings and generally match the column name from a given database table. It is
recommended to match the case of the key name as shown in the Swagger API documentation if possible.

Values

• String values are not case-sensitive.
• DateTime values should be provided in a valid ISO date format.

“resultColumns” Parameter

Besides the “query” parameter there is an associated “resultColumns” parameter.
This is used in conjunction with the “query” parameter to define the fields you wish to have returned in the response.
Without this parameter, the response will contain all document fields.

For example:

baseurl/JmJobList?Query={"job_no":2}&resultColumns={"L":["job_no","job_desc"]}

Where Job No. and Job Description fields will be included in the response.
Important to include the “L” top-level element.

PATCH Using POST Payload

(Included here as this method is currently not defined by the Swagger documentation)
PATCH method has the option to update a record using the same JSON payload structure as the POST call. This must include the header: 'Content-Type: application/json-patch+json'

Example Job update (cURL format):

curl --location --request PATCH

Note: The payload must include the existing primary key (job_no in the above example) as a URL parameter as well as in the body payload.

PATCH Using List Endpoints – GridUpdate

(Included here as this method is currently not defined by the Swagger documentation) List endpoints also support the PATCH method so that you can update multiple records using a query (see ‘GET – Query Parameters’ section above for details on available query parameters).
Example to update multiple jobs using the $in query parameter:

POST Commands, Mandatory Fields to Create

New Items

The Swagger model identifies many fields as nullable: false, which indicates that a value must be provided when the item is written to the database. However, in some cases, the business logic will provide default values, so it may not be strictly necessary to pass values for these properties in a given POST call to the API to create a new record. 
For example, in a basic payload to create a Work Order, Swagger identifies at least 25 fields as nullable: false, but the most basic payload to create a Work Order is:

Optional Headers

SaveArgument

In some cases, you must also add a header with the SaveArgument parameter to apply values passed as part of an API call. For example, when creating a Work Order, to apply a Work Order Template you must provide the wo_template_no value as well as set the SaveArguement header:

Key: SaveArgument                                 Value: {"LoadTemplate":"2"}

Source-Time-Zone-Name

The REST API uses Date time formats in ISO format with an optional offset value.

e.g. 2014-11-03T22:20:00+00:00

If you omit the offset value when using POST to create a record, you can use a header parameter to set the time zone your dates are using.
Key: Source-Time-Zone-Name                 Value: {Windows Time Zone name}

e.g. : header 'Source-Time-Zone-Name: Pacific Standard Time '

Will create records using Pacific Standard Time as the time zone for the payload times.
Remember to omit the offset values in your time formats.

Appendix A – Document List

There are over 1000 individual documents available to the Platform’s REST API. Below is a small sample of those documents. The full list of available documents can be obtained directly from the Platform using the Document Customizations query found in the System module. Specific documentation on each document can be found via the Swagger site.

Appendix B – Swagger Examples