Search

Customize Your API

Version 23.4.8841

Customize Your API

Arc includes a wizard for building APIs based on tables in your database. Access the wizard from the Resources tab. Arc supports a variety of databases.

Your API resources 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.

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

Your API resources 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. See Scripting for details.

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.

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: Some databases return data from an INSERT statement: for example, the generated Id of the new record. 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 primary key required input 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: You can specify multiple HTTP methods to be handled by the script.

In addition, 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 Introduction to ArcScript for more information on the following keywords used in this section:

Typical Customizations

This section describes some common schema 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, and that your cache does not contain the column.

Note: 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 alias attribute that contains the new column name.

Note: 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: 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>