The resources of your APIs are defined by authoring text-based schemas. Schemas are written in API Script, 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, API Script is a full-featured language with constructs for conditionals, looping, etc. However, as shown by the example schema, for most resource definitions you will 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 the edit button 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 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 api:info block of the schema, you can mark up the columns of the resource with these attributes and others.

<api: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"  />
</api:info>

Getting Data

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

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

The preceding request maps to the SQL query below:

SELECT * FROM Cars WHERE Make = 'Honda'

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

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

Posting Data

When a POST request is received, the API Server 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 SQL query below:

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

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

<api:script method="POST">
  <api:push op="apiInsert"/>
</api: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 api:push keyword, as with GET.

Putting Data

When a PUT request is received, the API Server 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://localhost:8065/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 below, 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 api: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 api:call keyword is used to invoke the operation instead. You can call the apiUpdate operation to execute updates to databases.

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

Deleting Data

When a DELETE request is received, the API Server 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 SQL query below:

DELETE FROM Cars WHERE Id = '1000'

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

<api:script method="DELETE">
  <api:validate attr="Id" desc="An Id is required to delete." />
  <api:call op="apiDelete"/>
</api: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.

<api:script xmlns:api="http://www.rssbus.com/ns/rsbscript/2">
 
  <!-- Define columns and the database connection in the api:info block -->
  <api: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" />
  </api: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. -->
  <api:script method="GET">
    <api:push op="apiSelect"/>
  </api:script>
 
  <!-- The POST method is executed when an HTTP POST is received. You can configure insert operations here. Use api:push to return the Id of the new record. -->
  <api:script method="POST">
  <api:validate attr="Make" desc="Make and Model are required to insert a Car."/>
  <api:validate attr="Model" desc="Make and Model are required to insert a Car."/>
    <api:push op="apiInsert"/>
  </api: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 api:call is used to invoke the operation. -->
  <api:script method="PUT,MERGE,PATCH">
    <api:validate attr="Id" desc="Id is required to update."/>
    <api:call op="apiUpdate"/>
  </api: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. -->
  <api:script method="DELETE">
    <api:validate attr="Id" desc="Id is required to delete."/>
    <api:call op="apiDelete"/>
  </api:script>
 
</api:script>

Keyword Reference

See the API Script for more information on the keywords used in this section:

• api:info
• api:set
• api:script
• api:validate
• api:call
• api:push