Version 23.4.8841

• HTTP Methods
  • GET
  • POST
  • PUT
  • DELETE
• Filtering Resources
  • Single Resource
  • Filtering
• Selecting Properties
• Sorting
• Pagination
  • Server-Side
  • Client-Side
  • Count-Only

The resources in the Arc API use JSON-formatted OData as the default REST protocol for accessing data. Other Web service formats are supported, including OData (Atom), JSONP, HTML, and CSV.

HTTP Methods

Resources are objects exposed in your API that can be queried, created, updated, and deleted. Resources can support the full range of create, read, update, and delete (CRUD) operations or be restricted to only a few. This section describes the HTTP methods used to perform CRUD operations on resources exposed by the application.

GET

You can use an HTTP GET request to retrieve a resource or a set of resources from the server. The following is an example request for an entire collection:

GET http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars

Here is the corresponding response:

{
  "@odata.context": "http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
  "value": [
    { "Id": "Id_1", "Color": "Color_1", "Model": "Model_1"},
    { "Id": "Id_2", "Color": "Color_2", "Model": "Model_2"},
    { "Id": "Id_3", "Color": "Color_3", "Model": "Model_3"}
  ]
}

POST

You can use an HTTP POST request to create a new resource. The request must contain the inputs required to create the resource. The following is an example request:

POST http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars
{
  "Color": "Color_1", "Model": "Model_1" 
}

Here is the corresponding response:

{
	"@odata.context":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
	"value": [
		{ "Color": "Color_1", "Model": "Model_2" }
	]
}

PUT

You can use an HTTP PUT request to update a resource. The primary key is required. The following is an example request:

PUT http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('Id_1')
{
  "Color": "Color_1", "Model": "Model_1"
}

Here is the corresponding response:

{
	"@odata.context":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars/$entity",  
	"Id": "Id_1", "Color": "Color_1", "Model": "Model_1"
}

DELETE

You can use an HTTP DELETE request to delete a resource. The primary key is required. The following is an example request:

DELETE http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars/('Id_1')

The response is empty with a 204 No Content HTTP status line.

Filtering Resources

You can use an HTTP GET request to retrieve all resources, filter resources, sort resources, and restrict the data returned from each resource. The path of the URL specifies the set of resources to retrieve. For example, to retrieve all Cars resources, use the following URL:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars

Single Resource

To retrieve a single resource, make a request to the URL for that resource. To construct the URL, use the desired resource’s primary key. For example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000')

Some resources might have multiple primary keys, which are indexed as shown in the following example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars(Id='1000', Date='2016-07-01')

Filtering

Client applications can retrieve multiple resources based on filters provided in the request. For example, a filter to retrieve all resources where Make matches ‘Honda’ would look like this:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=Make eq 'Honda'

The application supports the following logic operators for comparison:

You can also use and and or to combine multiple filters. For example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=Make eq 'Honda' and Date lt '2016-07-01'

You can use the startswith, endswith, toupper, tolower, and contains functions with the $filter query option. For example, the following request returns resources with properties that contain the specified substring:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=contains(Make,'Honda')

Selecting Properties

To retrieve a subset of properties, use $select, as shown in the following example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$select=Id,Model

This returns the Id and Model properties for all resources that match the filter in the request.

You can also retrieve an individual property value for a single resource, as shown in the following example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000')/Model/$value

Sorting

You can use $orderby to sort resources, as shown in the following example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$orderby=Model asc, Color desc

This returns the resources sorted by Model (ascending) and then by Color (descending).

Pagination

Server-Side

The application supports server-side paging. Enable this option in Settings > Server. When the page size is greater than 0 and a request returns results larger than the page size, the URL for the next page of results is included in the @odata.nextlink attribute of the response. The last page of results does not include this attribute. This URL includes a paging token which remains valid for the next two minutes. For example, the following response has three resources and an @odata.nextLink attribute containing the URL for the next page of records:

{
  "@odata.context": "http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
  "value": [
    { "Id": "Id_1", "Color": "Color_1", "Model": "Model_1"},
    { "Id": "Id_2", "Color": "Color_2", "Model": "Model_2"},
    { "Id": "Id_3", "Color": "Color_3", "Model": "Model_3"}
  ],
  "@odata.nextLink":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$skiptoken=0f87696b-aa28-4a70-b13d-c86af8338c80"
}

Client-Side

Arc also supports client-side paging using $top, $skip, and $count.

You can use $top=n to include only the first n resources in the result. For example, use the following request to show the top ten Cars resources:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10

You can use $skip=n to exclude the first n resources from the result. You can use $top with $skip to implement client-side paging. $skip is always applied before $top, regardless of their order in the query. For example, the following two queries retrieve the first 20 resources in two pages:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10
http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10&$skip=10

You can set $count to true to return the total number of records in the results. If you are using OData version 2.0 or 3.0, you can set $inlinecount to allpages instead. For example, consider the following query:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=3&$skip=4&$count=true

This query might return a response like the following:

{
  "@odata.context": "http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
  "@odata.count": 402,
	"value": [
    { "Id": "Id_1", "Color": "Color_1", "Model": "Model_1"},
    { "Id": "Id_2", "Color": "Color_2", "Model": "Model_2"},
    { "Id": "Id_3", "Color": "Color_3", "Model": "Model_3"}
  ],
  "@odata.nextLink":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Account?$skip=7"
}

The total count that matches the filter is returned in the response along with the single page of results.

Count-Only

You can retrieve just the count for resources matching a particular filter with the query, as shown in the following example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$count=true&$filter=Make eq 'Honda'

The response is a raw count of resources matching the filter in the request.