Introduction to the Data API

API URL Patterns

All the API calls follow the same URL pattern:

GET {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/OBJECT_PATH?parameters 
POST {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/OBJECT_PATH 
GET/PUT/DELETE {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/OBJECT_PATH/uid

Where:

• The {{IRIS-SERVER}} part is the server information of the InterSystems IRIS® instance. In a locally deployed server, it may look like http://localhost:52773

• The {{DATAMODEL-PATH}} part is the API base URL, such as /api/scdata/v1

• The OBJECT_PATH part is simply the object name in lower case plural form, such as salesorders or customers. See the table below for all object values.

• The first URL pattern gets data for an object, or searches for objects using a set of parameters. Any attributes of the object can be used in a search criterion.

• The second URL pattern creates a new object record. The body of the request should include the JSON string for the new object.

• The third URL pattern retrieves, updates, or deletes an object record by its uid (which is the external primary key).

Some examples:

• Finding all sales orders with status Open or PartialShip:

  GET {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/salesorders?orderStatus=Open,PartialShip 
  

  

• Creating a new customer:

  POST {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/customers 
  

  

  with the following JSON in the request body:

  {
      "uid" : "CUST-TEST-101",
      "name" : "Google",
      "type" : "HighTech",
      "contact" : "Ming",
      "url" : "https://google.com"
  }
  

  

• Retrieving a supply shipment record with uid value SUP-SHIP-1001:

  GET {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/supplyshipments/SUP-SHIP-1001
  

  

• Updating a location record:

  PUT {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/locations/LOC-PLANT-002 
  

  

  with new location JSON data in the request body.

Search APIs

Searches are supported through GET APIs with one or multiple URL parameters; each parameter maps to one search condition. If more than one parameter are used, the parameter conditions are combined with logical AND operation. For example, the following searches all Lenovo laptop products:

GET /products?brand=Lenovo&category=laptop

Each parameter name should match exactly an attribute name of the primary object. In some cases, attributes from secondary objects (contained or referenced objects) can also be used. For example, some product attributes can be used in an order search.

The search parameter value can be a single value, a list of values, or a range of values, as follows:

• Single value. This is the simplest search criterion, using the format parameterName=value. If the parameter is a string or a list of strings, the value matching is case-insensitive. So brand=lenovo is the same as brand=Lenovo.

• List of values. For a condition that requires matching any of the values in a list, you can provide a list of values as a comma-separated string. For example, to find products of either Lenovo brand or Dell brand, you can use brand=Lenovo,Dell. The list can be used for all data types, string, date, or numbers.

• Range of values. For date and numerical values (including currency), a range can be used in a search parameter. A range is specified by two values, separated by .. (two dots), in format of min..max. Both values are inclusive for the range. For example, price=100..200 fins all records with price in range of 100 (including 100) and 200 (including 200). The two range boundary values are not always required, and if one is missing, it means that boundary does not exist. For example, price=..200 means any record with price less than or equal to 200, while price=100.. means any record with price greater than or equal to 100.

• Null value. For any data type, you can search for records with an attribute not set (that is, a null value), or an attribute with some value set (that is, not null). For such cases, you can use two special string values NULL and NOTNULL for any attribute, such as attr1=NULL&attr2=NOTNULL

For example, this call finds all laptop computers from either Lenovo or Dell with price range between 500 and 1000:

GET /products?category=laptop&brand=Lenovo,Dell&price=500..1000

Sorting of Results

When more than one record is returned by an API call, you can define the order of the response data by specifying the sorting parameter sortBy. The value of this parameter must be a comma-separated list of attribute names of the primary object returned.

For example, the following API call defines how a list of orders should be sorted in the response:

GET /salesorders?sortBy=customer,orderValue

which defines the sorting to be first by customer, and then by order value.

By default, sorting is done in ascending order. To change the order to descending, use the - sign before the attribute name, such as the following example, which first sorts by customer in ascending order, and then by orderValue in descending order:

GET  /salesorders?sortBy=customer,-orderValue

Default Sorting

If no sorting parameter is provided in the request URL, a default sorting is applied, based on the primary object returned. The following table lists the default sorting parameters for each object type:

Pagination of Results

By default, any API call that returns multiple records returns the first 100 records that match the given criteria. You use pagination parameters to obtain additional records or a larger set of records. The pagination parameters give you the control needed to, for example, populate a table in a web UI, without excess resource consumption (memory, network bandwidth, and so on) or performance issues.

The pagination parameters are as follows:

• pageSize. This parameter defines the maximum number of record returned in the API call. The actual number of records returned can be less or equal to this value. The value is 100, and the maximum allowed value is 1000.

• pageIndex. This parameter specified the page index (starting from 0), to be returned in the response. The default is 0.

For example, the following API call skips the first 200 orders and returns the next 100 orders, sorted by order value:

GET  /salesorders?sortBy=orderValue&pageSize=100&pageIndex=2

When a response returns only partial records using pagination, the following HTTP header parameters are populated in the response. Use these values to control the pagination logic in the UI.

• pageSize. The same value if specified in the request path parameter. Returns the default value if not explicitly specified in the request.

• pageIndex. The same value if specified in the request path parameter. Returns the default value if not explicitly specified in the request.

• returnCount. Number of records returned in the current response. This value is less than or equal to pageSize

Date and Date/Time Formats

For any date or date/time attribute, you must specify the value in ISO 8601 format, whether you provide this in the message JSON body or in the HTTP parameter.

Here are some examples. For date attributes:

2021-02-28

For date/time attributes (the following two values are equivalent):

2021-12-15T13:23:15-05:00
2021-12-15T18:23:15Z

If the time zone information is missing, the UTC time is assumed. For example, 2021-05-24T08:30:00 is treated the same as 2021-05-24T08:30:00Z