Search

API Connector

Version 22.0.8473

API Connector

The API Connector supports publishing custom API’s at an CData Arc endpoint. If you are looking for an API client to consume APIs, use the REST Connector instead.

Overview

The API Connector exposes tables, views, and stored procedures from a database as a web API. The API Connector reads the available tables, views, and stored procedures from the target database, then any subset of these can be exposed as API resources.

API Connectors can also be used to expose a custom scripting endpoint. When an API call is made to a custom script, the script is executed to build the API response. Custom scripting is an extremely flexible approach to providing Arc resources as responses to web requests.

Connector Configuration

This section contains all of the configurable connector properties.

Connection Tab

Configuration

Settings that determine how the API can be accessed.

  • Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
  • Connector Description An optional field to provide free-form description of the connector and its role in the flow.
  • API Endpoint The URL at which the custom API will be published. To access a specific resource, append a slash and the resource name to this URL value.
  • API Documentation The URL at which the documentation for the custom API will be published.

Connection

Settings related to the database connection.

  • Data Source Type The type of database to connect to.
  • Settings Format Whether to specify a set of individual connection properties or a single connection string containing each of the properties.
  • Connection String The database credentials in connection string format. Only applicable when Settings Format is set to Connection String.
  • Server The host name or IP address of the server hosting the database.
  • Port The port on which to connect to the database host.
  • Database The name of the database to connect to.
  • User The user credential that has permission to access the database.
  • Password The password credential associated with the specified User.

Advanced Section

Advanced settings are auto-generated based on the configured Data Source Type. For more information on an advanced setting, please see the documentation for the connector that matches the data source (e.g. please see the MySQL Connector documentation for advanced settings when the Data Source Type is MySQL).

Other Settings

Settings that do not fall into the previous categories.

  • Log Subfolder Scheme Instructs the connector to group files in the Logs folder according to the selected interval. For example, the Weekly option instructs the connector to create a new subfolder each week and store all logs for the week in that folder. The blank setting tells the connector to save all logs directly in the Logs folder. For connectors that process many transactions, using subfolders can help keep logs organized and improve performance.
  • Log Messages Whether the log entry for a processed file will include a copy of the file itself.
  • Save to Sent Folder Whether files processed by the connector should be copied to the Sent folder for the connector.

Miscellaneous

Settings for specific use cases.

  • Other Settings Allows configuration of hidden connector settings in a semicolon-separated list, like setting1=value1;setting2=value2. Normal connector use cases and functionality should not require use of these settings.

Resources Tab

Resources

The list of API resources exposed by the connector. Each Resource is generated from a table or view present in the connected database. Adding a new resource exposes new database data to a web API call via the connector.

Actions Tab

Actions

The list of API actions exposed by the connector. Each Action is generated from a stored procedure present in the connected database. Adding a new action exposes new database data to a web API call via the connector.

Users Tab

Users

The list of users authorized to make API calls to the connector. Users can be restricted by HTTP method (GET, POST, etc), number of requests per hour, and number of concurrent requests. API credentials can also be managed on a by-server basis in the Server tab.

Server Tab

Trusted IP Addresses

This section defines the IP addresses that are allowed to make connections. The following functions are available:

  • Add Opens a modal to enter a new IP address range.
  • Edit Opens a modal to modify the selected IP address range.
  • Delete Deletes the selected IP address range from the list.

The following restrictions apply to this feature:

  • localhost cannot be modified or removed from the list.
  • Any IP addresses outside of the defined ranges will be rejected.
  • Ranges are supported. For example, the entry 100.10.100.1-15 indicates that IP addresses between 100.10.100.1 and 100.10.100.15 are allowed.
  • CIDR notation is supported. For example, the entry 100.10.100.0/24 indicates that IP addresses between 100.10.100.0 and 100.10.100.255 are allowed.
  • Wildcard patterns are supported. For example, the entry 100.10.100.* indicates that IP addresses beginning with 100.10.100 are allowed.

Default Rate Limits (Per User)

Settings restricting the number of API requests allowed.

  • Max Requests Per Hour The limit to the number of requests a single user can issue in an hour.
  • Max Concurrent Requests The limit to the number of concurrent requests a user can issue.

Cross-Origin Resource Sharing (CORS)

Settings governing the use of CORS to serve cross-origin resources.

  • Enable cross-origin resource sharing (CORS) Whether or not CORS is enabled.
  • Allow all domains without ‘*‘ If enabled, domain origins will not be restricted to a specific list.
  • Access-Control-Allow-Origin The comma-delimited list of domain origins to allow. Included as an HTTP response header.
  • Access-Control-Allow-Credentials Whether or not user credentials such as cookies are allowed in cross-origin requests. Included as an HTTP response header.
  • Access-Control-Allow-Methods The comma-delimited list of methods to allow. Included as an HTTP response header.
  • Access-Control-Allow-Headers The comma-delimited list of headers to allow. Included as an HTTP response header.
  • Access-Control-Max-Age The maximum duration that Access-Control response header values can be cached.

OData

Settings related to OData feature support.

  • Server-Side Paging Size The number of results per-page returned by an OData request. All results will be returned when this option is set to 0.
  • Default Format The OData format to be used when the client does not specify a format.
  • Default Version The OData version to be used when the client does not specify a format.
  • Date Time Format The format to use when returning date-time information.
  • Base URL The fully qualified URL of the OData endpoint. If unspecified, Arc will attempt to create the base URL based on the incoming request.

Establishing a Connection

Before creating your first API, you need to connect to your data store. Arc supports connecting to relational databases, file stores, and back-end services such as other APIs.

Once you select the data store type on the connection page, a list of connection properties is generated for the selected data store. Enter your credentials for connecting to the data store and save your changes on this page. Click Test Connection to make sure the app is connected to your data store.

Note: The application includes drivers for some common databases, but may not include drivers for all the data sources it supports. For drivers that are not included, make sure to follow the instructions below for your machine type.

Windows Edition

Install the ADO.NET provider on this machine, restart the server, and retry connecting to your data store.

Java Edition

Copy the JDBC driver to the lib folder of your Java Web server.

Building Your First API

After defining a connection to your data source, you can surface the resources of your API. You can use the wizard in the administration console to generate schemas for reading and writing to your data store.

Surfacing Database Resources

To use the wizard to model a database as an API:

  1. Click Resources > Add Resource.
  2. Select a table you want to model as an API.
  3. Select the columns you want to surface in the resources.

The resource is defined in a schema, which can easily be modified or extended without regenerating from the database. You can modify the schema by clicking the resource or Edit in the entry for the resource. The generated schema contains the two essential components of a schema:

  • An info block containing resource columns definitions
  • Methods that correspond to HTTP methods and call data processing operations

Querying Your API

After creating resources for your API, you can expose them to authorized users and IP addresses. Arc uses auth token-based authentication and supports the major authentication schemes. Click the Users tab to manage auth tokens and permissions for users. To define the IP addresses allowed to access the application, click the Server tab.

You can now query your API in the browser, as shown in the example query and response below.

Request

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

Response

{ 
  "@odata.context":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
  "value":[
    { "Id": "10001", "Model": "MyModel1", "Color": "Red" },
    { "Id": "10002", "Model": "MyModel2", "Color2": "Blue" },
  ]
}

API Management

Arc enables you to create and manage an API that allows integration with other applications. This API contains Web services that are secure and remotely accessible from any application, browser, or smart device. The resources in this 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.

You can browse your APIs and manage access to them in the administration console. Click API on the navigation bar to view documentation and examples of accessing the API. Go to the application settings to manage your connection settings, resources, users, and server settings for your API.

This section contains topics related to designing and managing your API.

API Resources

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

An HTTP GET request can be used 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

An HTTP POST request can be used 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

An HTTP PUT request can be used 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

An HTTP DELETE request can be used 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.

Overriding HTTP Methods

Some clients may not be capable of issuing the correct HTTP method for a specific operation. You can use the @x-http-method query string input parameter or the X-HTTP-Method HTTP header to override the HTTP method for a request. For example, a client that does not support the HTTP PUT method can include the X-HTTP-Method: PUT header with a GET request to issue an update request for a resource.

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 may 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 the following:

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

The application supports the following logic operators for comparison:

Eq Equal
Ne Not Equal
Gt Greater Than
Ge Greater Than or Equal
Lt Less Than
Le Less Than or Equal
Not Negation

You can also use and and or to combine multiple filters:

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

The startswith, endswith, toupper, tolower, and contains functions can be used 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 properties Id and Model 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, which can be enabled in the Settings > Server section of the application. 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 also set the parameter $count to true to return the total number of records in the results. If 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 may 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"
}

As you can see, the total count that matches the filter is returned in the response along with the single page of results.

Count-Only

You can retrieve the count only 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.

API Actions

Actions can be used to extend the set of operations on resources and to execute unrelated actions on the server. Actions must be executed as an HTTP POST request. The following is an example action invocation:

POST http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/WashCar/
{
  Wax: "Wax_1"
}

Here is the corresponding response:

{"Complete": "Complete_1"}

Use URL Parameters as Input

In cases where the client does not support the HTTP POST method, the Action can be invoked using the URL parameters @x-http-method. The inputs for the Action can then be specified as additional URL parameters:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/WashCar?@x-http-method=POST&URLparam1=my\_url\_parameter1&urlparam2=my\_url\_param2

Discovery

Based on the OpenAPI specification, the application’s APIs are fully documented and discoverable. The APIs can be accessed from standard JavaScript, applications compliant with OpenAPI, or any application that supports the OData standard. The following sections show how to use these standards to discover the APIs.

Service Document

The service document is a simple listing of all the APIs in the JSON format by default. The service document is returned from the service root, where all requests are made, including metadata discovery requests. The following is an example of the service root:

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

To retrieve more detailed information, make a request to the metadata URL.

Metadata URL

The application exposes the capabilities of its APIs to OData consumers through the OData metadata document URL. The metadata document is returned as XML and contains column data types, the key of the resource, and other information. You can access the complete metadata resource by appending $metadata to the service root, as shown in the following example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata

To access the metadata for a resource, append $metadata to the resource URL of the resource:

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

OpenAPI Definition

OpenAPI (Swagger) definitions are generated for the data sources you surface through the application.

To obtain the Swagger definition, append $swagger to the service root, as shown in the following example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$swagger

Server Responses

The following is a list of typical server responses to API resources and descriptions of when to expect such responses.

200 OK The request was processed by the server without error.
201 Created The request was successful and the specified was created by the server.
204 No Content A request returns this status if the requested resource has a null value or the service applies a return=minimal preference.
400 Bad Request The request was not understood or was missing required parameters.
401 Unauthorized The user was not authenticated or authorized to access this resource.
403 Forbidden Access is denied to this resource.
404 Not Found The resource does not exist.
405 Method Not Allowed The HTTP method specified is not allowed for this resource.
429 Too Many Requests The user has sent too many requests in a given amount of time, or exceeded the maximum amount of concurrent requests.
501 Not Implemented The server does not support the functionality required to fulfill the request. This response is returned when the server does not recognize the request method and is not capable of supporting it for any resource.

Users

Arc uses auth token-based authentication to control per-user access to the API. Authtokens are unique, randomly generated identifiers that users authenticate to an API with. Authtokens also represent the user’s current permissions.

Authtokens enable you to connect using any of the major authentication schemes. For example, to use HTTP Basic authentication, set the username in the User header and the user’s corresponding authtoken in the Password header. See Authentication for more information on authenticating to the API.

Adding Users

To add a user, navigate to the Users tab for the connector, and click Add. In the resulting dialog, enter the following information:

  • Name: Enter a username to be used in HTTP authentication.
  • Privileges: Select the HTTP methods the user is allowed to access, GET, POST, PUT/PATCH/MERGE, or DELETE. These correspond to SELECT, INSERT, UPDATE, and DELETE statements, respectively.
  • Max. Requests: Enter the maximum requests per hour for this user. A value of 0 allows the user unlimited access per hour.
  • Max. Concurrent Requests: Enter the maximum number of requests that can be sent simultaneously. A value of 0 allows the user unlimited simultaneous requests.

Note that user-specific settings override server-wide API limit settings. An empty value for one of the user settings uses the server default.

Configuring the User Database

Arc stores user information in an SQLite database by default. You can also save user information to the database of your choice. If you are using the embedded server, specify the connection string to the caching database in the connectionStrings element of the Web.config. Otherwise, refer to the documentation for the server you are hosting the application on.

Authentication

Users access API resources by providing auth tokens with requests. You can manage users and auth tokens on the Users tab of the API Connector settings pane.

Before users can call the API, you also need to set trusted IP addresses for connections. These settings are available on the Server tab of the API Connector settings pane. By default, all IP addresses are restricted.

Using Auth Tokens in Basic Authentication

Enter the user’s auth token as the password when using Basic Authentication.

Using Auth tokens in the HTTP Header

Add the HTTP header x-cdata-authtoken with the desired auth token as part of the HTTP request.

Using Auth Tokens as Query String Parameters

To allow the connector to pass the auth token in query string parameters, open the Server tab of the API Connector settings pane and select Allow authtoken in URL in the Advanced Settings section.

After enabling this feature, you can specify the auth token as the value of the @authtoken parameter, which can be supplied as part of the HTTP form-post data or a query parameter.

Rate Limiting

You can configure both per-user usage limits and server-wide defaults.

Server Defaults

To configure the default rate limits applied to all users, navigate to the Server tab for the connector. The following options can be configured on this page:

  • Max. Requests Per Hour: Enter the default maximum requests allowed per hour per user. A value of 0 allows unlimited requests per hour by default.
  • Max. Concurrent Requests: Enter the default maximum simultaneous requests allowed per user. A value of 0 allows unlimited simultaneous requests by default.

User-Specific Limits

To configure rate limits for an individual user, navigate to the User tab for the connector, select a user, and click Edit. The following options can be configured in the resulting dialog:

  • Privileges: Select the HTTP methods the user is allowed to access, GET, POST, PUT/PATCH/MERGE, or DELETE. These correspond to SELECT, INSERT, UPDATE, and DELETE statements, respectively.
  • Max. Requests (hr): Enter the maximum requests allowed for this user per hour. A value of 0 allows the user unlimited requests per hour.
  • Max. Concurrent: Enter the maximum simultaneous requests allowed for this user. A value of 0 allows the user unlimited simultaneous requests.

User-specific rate limits override the server defaults. An empty value for one of the user settings will use the server default.

CORS

You can configure cross-origin resource sharing (CORS) on the Server tab. CORS allows browser-based clients to connect to Arc. Without CORS, browser-based scripts cannot connect to Arc because of the same-origin policy enforced by the browser. This policy restricts client-side scripts and documents from loading resources outside their origin. The origin of a script consists of the protocol, host, and port.

When the option to enable CORS is selected, you can set the following options to configure CORS:

  • Allow all domains without *: When this option is set, the application allows any origin passed by the client by returning that origin in the Access-Control-Allow-Origin header.

  • Access-Control-Allow-Origin: Enter the origins for which the application will participate in CORS. The application returns these origins in the Access-Control-Allow-Origin header. When this is set to ‘’, the application allows any origin and pass ‘’ in the Access-Control-Allow-Origin header. This is suitable for public APIs.

    When this is set to *, the application will allow any origin and pass * in the Access-Control-Allow-Origin header. This is suitable for public APIs.

  • Access-Control-Allow-Methods: Enter a comma-separated list of allowed methods.
  • Access-Control-Allow-Headers: Enter a comma-separated list of headers that can be used in requests made by the script.
  • Access-Control-Allow-Credentials: Set this to true if you want to require that clients provide credentials.
  • Access-Control-Max-Age: Enter the number of seconds the user agent can cache preflight requests.

Additional Output Formats

In addition to the default JSON format that all resources and actions support, the API also supports the following formats: XML, JSONP, RSS, HTML, CSV, and TSV.

XML

You can request the XML (OData Atom) format by adding the $format=atom query parameter or by adding the HTTP Accept header with the value application/xml to the request. See the example request and response below.

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$format=atom

Response

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:base="http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/" xmlns:m="http://docs.oasis-open.org/odata/ns/metadata" xmlns:info="http://arc.cdata.com/ns?RsbOps/v2/" xmlns:d="http://docs.oasis-open.org/odata/ns/data">
  <title type="text">Cars</title>
  <id>http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars/</id>
  <updated>2015-04-23T18:36:20-04:00</updated>
  <entry>
  <title>1000</title><id>http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000')</id>
  <category term="Arc.Cars" scheme="http://docs.oasis-open.org/odata/ns/scheme" />
  <link rel="edit" title="Cars" href="Cars('1000')"/>
  <content type="application/xml">
    <m:properties>
      <d:Id m:type="String">1000</d:Id>
      <d:Model m:type="String">Accord</d:Model>
    </m:properties>
  </content>
  </entry>
</feed>

JSONP

You can request the JSONP format by adding the $callback=myCallback query parameter, “where myCallback is the name of the function you would like to wrap the JSON result. See the example request and response below.

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$callback=myCallback

Response

myCallback(
  {
    "@odata.context": "http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
    "value": [
      {
        "Id": "1000", 
        "Model": "Accord"
      },
      ...
    ]
  }
);

RSS

You can request the RSS format by adding the query parameter @rss to the request. See the example request and response below.

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?@rss

Response

<rss xmlns:arc="http://arc.cdata.com/ns?RsbOps/v2/" xmlns:ls="http://www.microsoft.com/schemas/rss/core/2005" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:x="http://arc.cdata.com/ns?RsbOps/v2/anonymous/" xmlns:odata="http://arc.cdata.com/ns?RsbOps/v2/anonymous/" xmlns:info="http://arc.cdata.com/ns?RsbOps/v2/anonymous/" xmlns:data="http://arc.cdata.com/ns?RsbOps/v2/anonymous/" version="2.0">
  <channel>
    <description>Retrieves and updates Cars information</description>
    <generator>Arc - http://arc.cdata.com</generator>
    <link>http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?@html</link>
    <title>Cars</title>
    <item xmlns:x="http://arc.cdata.com/ns?RsbOps/v2/anonymous/">
      <x:Id>1000</x:Id>
      <x:Model>Accord</x:Model>
    </item>
  </channel>
</rss>

HTML

You can request the API response to be formatted as a simple, unstyled HTML table by adding the query parameter @html to the request. See the example request and response below.

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?@html

Response

<table>
  <tr><th>Id</th><th>Model</th></tr>
  <tr><td>1000</td><td>Accord</td></tr>

CSV

You can request the API response to be formatted as CSV data by adding the query parameter @csv to the request. See the example request and response below.

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?@csv

Response

Id,Model
1000,Accord

TSV

You can request the API response to be formatted as TSV data by adding the query parameter @tsv to the request. See the example request and response below.

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?@tsv

Response

Id  Model
1000 Accord

Customizing Your API

Arc includes a wizard for building APIs based on tables in your database. The wizard can be accessed from the Resources tab. A variety of databases are supported.

The resources of your API are defined in text-based schemas that are easy to extend. To edit a schema, click Edit< next to the resource in the table on the Resources tab. </p>

You can also write your own schemas to surface files and back-end services as REST APIs; for example, you can surface XML as Web services.

Schema Definitions

The resources of your APIs are defined by authoring text-based schemas. Schemas are written in ArcScript, a simple configuration language that allows you to define the columns of the resource. It also has built-in operations that enable you to read and write to databases, files, and backend services.

In addition to these data processing primitives, ArcScript is a full-featured language with constructs for conditionals, looping, etc. However, as shown by the example schema, for most resource definitions you do not need to use these features.

The following sections describe a fully functional schema that enables bidirectional access to tables in an SQLite database; you can use the wizard on the Settings > Resources tab to generate similar schemas for your database tables and stored procedures. You can also edit schemas on this tab by clicking Edit next to the schema.

The following sections also detail all of the components needed to read and write to other data sources by writing your own schemas. Schemas for Resources are written in .rsd files; schemas for Actions are written in .rsb files. The wizard places these files in the API subfolder of the application root. You must place your custom schemas in this folder.

The following sections also detail all of the components needed to read and write to other data sources by writing your own schemas. Schemas for are written in .rsd files; schemas for are written in .rsb files. The wizard places these files in the api subfolder of the application root. You will need to place your custom schemas in this folder.

Mark Up Resource Columns

When connecting to databases, the columns of a resource have the following basic attributes:

  • Column name
  • Data type
  • Whether the column is a primary key.

Inside the arc:info block of the schema, you can mark up the columns of the resource with these attributes and others.

<arc:info title="NorthwindOData" desc="Access the Cars database through REST APIs." connection="SQLiteCars">
  <attr name="ID"           key="true" xs:type="int"      />
  <attr name="Make"                    xs:type="string"   />
  <attr name="Model"                   xs:type="string"   />
  <attr name="Cost"                    xs:type="double"   />
  <attr name="CreatedDate"             xs:type="datetime" />
  <attr name="InStock"                 xs:type="boolean"  />
</arc:info>

Getting Data

When an HTTP GET request is received, the application executes the GET method of the schema. In this method, you can call the application’s built-in operations to process data retrieval requests. The following is an example search request using an HTTP GET:

GET api.rsc/Cars?$filter=Make eq 'Honda'

The preceding request maps to the following SQL query:

SELECT \* FROM Cars WHERE Make = 'Honda'

In the corresponding GET method, the results from the database query are pushed to the application’s HTTP response with the arc:push keyword. You can use the apiSelect operation to execute search, sort, summary, and other data retrieval queries to databases.

<arc:script method="GET" >
  <arc:push op="apiSelect"/>
</arc:script>

Posting Data

When a POST request is received, the application executes the POST method of the schema, where you can call data manipulation operations, such as insert.

For example, consider the following HTTP POST request:

POST api.rsc/Cars
{
  "Model": "Civic",
  "Make": "Honda"
}

The preceding request maps to the following SQL query:

INSERT INTO (Model, Make) VALUES ('Civic', 'Honda')

In the corresponding POST method, you can use the apiInsert operation to execute inserts to databases.

<arc:script method="POST">
  <arc:push op="apiInsert"/>
</arc:script>

Note that some databases return data from an INSERT statement; for example, the generated Id of the new record. If you want to access values returned from an insert, use the arc:push keyword, as with GET.

Putting Data

When a PUT request is received, the application executes the PUT method of the schema, where you can call data manipulation operations, such as update.

For example, consider the following PUT request:

PUT http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000') 
{ 
  "Model": "Civic"
}

The preceding request maps to the SQL statement below:

UPDATE Cars SET Model = 'Civic' WHERE Id = '1000'

In the corresponding PUT method, the required input, the primary key, is validated before the operation is called. You can check that an input was provided and alert the user otherwise with the arc:validate keyword. Note that you can specify multiple HTTP methods to be handled by the script.

Additionally, note that since updates do not typically return data, the arc:call keyword is used to invoke the operation instead. You can call the apiUpdate operation to execute updates to databases.

<arc:script method="PUT,MERGE,PATCH">
  <arc:validate attr="Id" desc="An Id is required to update." />
  <arc:call op="apiUpdate"/>
</arc:script>

Deleting Data

When a DELETE request is received, the application executes the DELETE method of the schema, where you can call delete operations. For example, consider the following HTTP DELETE request:

DELETE api.rsc/Cars('1000')

The preceding request corresponds to the following SQL query:

DELETE FROM Cars WHERE Id = '1000'

In the DELETE method, you can call the apiDelete operation to execute deletes to databases.

<arc:script method="DELETE">
  <arc:validate attr="Id" desc="An Id is required to delete." />
  <arc:call op="apiDelete"/>
</arc:script>

Schema Example

The following schema enables read and write access to a Cars table in an SQLite database. It contains all the components you need to access a database through HTTP.

<arc:script xmlns:arc="http://arc.cdata.com/ns/arcScript/2">

  <!-- Define columns and the database connection in the arc:info block -->
  <arc:info title="case" description="Create, Update, Query, and Delete Cars." connection="SQLiteCars"> 
    <attr name="Id"             key="true" xs:type="string"   />
    <attr name="Year"                      xs:type="int"      />
    <attr name="Make"                      xs:type="string"   />
    <attr name="Model"                     xs:type="string"   />
    <attr name="DatePurchased"             xs:type="datetime" />
  </arc:info>

  <!-- The GET method is executed when an HTTP GET is received. You can configure data retrieval operations here. The results of processing are pushed to the schema's output. -->
  <arc:script method="GET">
    <arc:push op="apiSelect"/>
  </arc:script>

  <!-- The POST method is executed when an HTTP POST is received. You can configure insert operations here. Use arc:push to return the Id of the new record. -->
  <arc:script method="POST">
  <arc:validate attr="Make" desc="Make and Model are required to insert a Car."/>
  <arc:validate attr="Model" desc="Make and Model are required to insert a Car."/>
    <arc:push op="apiInsert"/>
  </arc:script>

  <!-- The PUT method is executed when an HTTP PUT is received. You can configure update operations here. Within the script block, the primary key is used to update the record. Updates typically do not return data, so arc:call is used to invoke the operation. -->
  <arc:script method="PUT,MERGE,PATCH">
    <arc:validate attr="Id" desc="Id is required to update."/>
    <arc:call op="apiUpdate"/>
  </arc:script>

  <!-- The DELETE method is executed when an HTTP DELETE is received. You can configure delete operations here. Within the script block, the primary key is used to delete the record. -->
  <arc:script method="DELETE">
    <arc:validate attr="Id" desc="Id is required to delete."/>
    <arc:call op="apiDelete"/>
  </arc:script>

</arc:script>

Keyword Reference

See the ArcScript Reference for more information on the following keywords used in this section:

Typical Customizations

The resources for your data source are defined in simple, text-based schemas that are easy to extend. This section describes some often-used modifications. To edit a schema, click Settings > Resources and click Edit next to the resource you want to modify.

Remove a Column

Deleting an attr element from arc:info removes the column from the resource. This means that the API does not list the column; also, your cache does not contain the column. Note that it is important to delete the entire XML element for the column that you want to remove.

Change a Resource Column’s Data Type

To change a resource column’s data type, change the xs:type attribute to one of the following supported data types:

  • string
  • datetime
  • boolean
  • int
  • long
  • double

Rename a Resource Column

To rename a resource column, locate the element for the resource and add an attribute named alias containing the new name you want for the column. Note that you cannot change the name attribute. This value must remain consistent for the application to maintain the mapping to the correct column in the underlying data source.

The example below renames the Type column to APIType:

<arc:info>
  <attr name="Type" alias="APIsType" xs:type="string" columnsize="40" readonly="True" key="False" />
  ...
</arc:info>

Rename a Resource

You can rename a resource by changing the name of the resource’s .rsd file in the API subfolder of the application root. Note that the title attribute in arc:info must remain the same as the name of the table in the underlying data source.

Change the Data Source Connection

You can use the connection attribute in arc:info to change the connection for any given resource. This makes it easy to switch from a sandbox to a production instance.

Any changes you make to the connection in the administration console are picked up by all resources that reference the same connection in arc:info, as shown below.

<arc:info title="case" description="Create, Update, Query, and Delete the SQLite Cars database." connection="SQLiteCars">
  ... 
</arc:info>