OpenAPI Definition and Endpoints

Summary Index

From Platform version v10.2, an OpenAPI (previously referred to as Swagger) index page has been introduced to assist in the navigation and generation of OpenAPI definitions. The index page can be found by entering the base URL of your site (you use for accessing the Platform UI) and adding “/ApiDocs” to the end (e.g. www.xytechexample.com/XYT\_TEST/ApiDocs). The Xytech API Index page is displayed. 

API Index Page

Using the Index

The index page displays groups of endpoints called modules for the selected database. Clicking on a module will reveal the endpoints within that module. Click on an endpoint, and the OpenAPI definition will be generated using the Swagger UI.

The Index is comprised of the following areas:
- Selected Database: The name of the database currently selected for this host.
- Available Databases: (Where multiple databases exist on the same host) Click a database to select it and view its associated endpoint modules.
- Filter Documents: Enter text into this field and press [Enter] to display matching endpoint descriptions.
- Module and Document List: Only modules in the selected database are displayed. Click any Module to expand and show the endpoints it contains. Each endpoint has a label that describes its type (Document [maintenance], List, or Setup).

Demo OpenAPI definitions

See a demo of Xytech OpenAPI definitions here

Mandatory Fields Note

The OpenAPI definition model identifies many fields as mandatory (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 all mandatory fields to the API to create a new record. 
For example, in a basic payload to create a Work Order, OpenAPI identifies at least 25 fields as mandatory, but the most basic payload to create a Work Order requires 7.

For versions prior to v10.2

For versions prior to v10.2 you will need to generate the OpenAPI documentation manually for each document endpoint.
Use a browser to generate the OpenAPI 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 OpenAPI document and then display the OpenAPI document.
To display generated OpenAPI 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

Endpoint List

There are over 1000 individual documents (endpoints) 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 UI using the Document Customizations list found under the System module. Specific details on each document can be found via the OpenAPI definition

ID	Class Name	Document Description	Document Type
10315	JmJob	Job	Maintenance
315	JmJobList	Jobs	Select (List)
10317	JmJobStatus	Job Statuses	Setup
10318	JmJobTable1	Subscription	Setup
10322	JmJobType	Job Types	Setup
359	JmTrxReport	Transaction Reports	Select (List)
10339	JmWorkOrder	Work Order	Maintenance
10346	JmWoTransaction	Work Order Transactions	Maintenance