Adabas REST Interface

The Adabas REST Interface included in the package can be used to access data from any programming language that supports HTTP requests. The Adabas REST Interface provides an HTTP entry point to read (GET), search (SEARCH), update (PUT), insert (PUSH), and delete (DELETE) Adabas record data.

The server can deliver the response in two text formats, JSON and XML.

For information on how to configure the Adabas REST server before you use it for the first time, see Adabas for Linux, UNIX and Windows > Adabas REST Administration > Adabas REST Server.

The Adabas REST Server API is used to introduce the Adabas record data into the REST interface. The REST API is defined with the Swagger standard and the corresponding swagger.yaml file is included in the package.

A standard request URL to access data from a database has the following form:

http://host name:port/format/type/location reference

The host name is the name or the alias name of the machine on which the REST server is running. Ensure that this name can be resolved using the standard naming service mechanisms.

The port number is specified in the REST server configuration file.

The format specification is the first element of the request path. It represents the main point from which to query data. The /rest/ format is available. The default output format when you use REST is JSON. To receive the output in XML, change the Accept HTTP header to application/xml.

The type specification represents how to access the database. The available types are /db/ (direct access) and /map/ (access via a map definition). The Adabas map definition always contains a reference to the database ID and file number, so it is not necessary to specify them in the request.

The HTTP location reference path element defines the resource to be accessed. Depending on the type specification, the location reference contains the following path elements:

Type Path Element Explanation

Type	Path Element	Explanation
`/db/`	`database ID` `file number` `ISN` `Adabas field`	Specify the database ID and file number. To access a specific record, include its associated ISN and field in the database.
`/map/`	`map name` `ISN` `map field name`	Access a predefined datamap. To access a specific record in a datamap, include its associated ISN and field in the datamap.

/db/

database ID
file number
ISN
Adabas field

Specify the database ID and file number.

To access a specific record, include its associated ISN and field in the database.

/map/

map name
ISN
map field name

Access a predefined datamap.

To access a specific record in a datamap, include its associated ISN and field in the datamap.

Additionally to the location reference path, you may modify the request URL with a number of parameters in standard HTTP fashion, for example ?fileds=AC,AE&limit=10.

Parameter	Definition
`fields`	Defines a list of field requests for the returned data.
`start`	Defines the offset or ISN from which to start reading.
`limit`	Limits the number of returned entries.
`sorted_by`	Provides one field to be used to sort the returned data. That field must be an Adabas descriptor.
`search`	Searches for data that satisfies given search criteria, for example `AE='SMITH'` or `LastName='SMITH'`.

To access Adabas data, insert any of the following methods before the URL request:

GET
SEARCH
PUT
PUSH
DELETE
Example Application

GET

The HTTP GET method defines the access to read data from the Adabas REST server.

A request to read data out of database ID 4 and file 11 with ISN 1 would look like this:

GET
http://localhost:8190/rest/db/4/11/1

This request will return JSON data that looks as follows:

{"NrRecords":1,"FileRecords":-1,"Records":[{"ISN":1,"AA":"50005800","AB":
{"AC":"SIMONE","AD":"","AE":"ADAM"},"AF":"M","AG":"F","AH":712981,"A1":
{"AI":["26 AVENUE RHIN ET DA"],"AJ":"JOIGNY","AK":"89300","AL":"F"},"A2":
{"AM":"44864858","AN":"1033"},"AO":"VENT59","AP":"CHEF DE SERVICE","AQ":
[{"AR":"EUR","AS":963,"AT":[138]}],"A3":{"AU":19,"AV":5},"AW":
[{"AX":19990801,"AY":19990831}],"AZ":["FRE","ENG"]}]}

The XML response looks as follows:

<?xml version="1.0" encoding="UTF-8"?><Response><Record ISN="1"><Group sn="A2"><Field
sn="AN">1033</Field><Field sn="AM">44864858</Field></Group><Group sn="A1"><Multiple sn="AI"><Field
sn="AI">26 AVENUE RHIN ET DA</Field></Multiple><Field sn="AJ">JOIGNY</Field><Field
sn="AK">89300</Field><Field sn="AL">F</Field></Group><Group sn="A3"><Field sn="AU">19</Field><Field
sn="AV">5</Field></Group><Period sn="AQ"><Entry><Field sn="AR">EUR</Field><Field
sn="AS">963</Field><Multiple sn="AT"><Field sn="AT">138</Field></Multiple></Entry></Period><Period
sn="AW"><Entry><Field sn="AX">19990801</Field><Field sn="AY">19990831</Field></Entry></Period><Multiple
sn="AZ"><Field sn="AZ">FRE</Field><Field sn="AZ">ENG</Field></Multiple><Field
sn="AA">50005800</Field><Group sn="AB"><Field sn="AC">SIMONE</Field><Field sn="AE">ADAM</Field><Field
sn="AD"></Field></Group><Field sn="AG">F</Field><Field sn="AH">712981</Field><Field sn="AF">M</Field><Field
sn="AO">VENT59</Field><Field sn="AP">CHEF DE SERVICE</Field></Record></Response>

A request to read data out of a map definition (MY-EMPLOYESS-MAP) with database ID 4 and file 11 (EMPLOYEES-NAT) with ISN 1 looks as follows:

GET
http://localhost:8190/rest/map/MY-EMPLOYEES-MAP/1

This request returns JSON data that looks as follows:

{"NrRecords":1,"FileRecords":-1,"Records":[{"ISN":1,"personnnel-
id":"50005800","full-name":{"name":"ADAM","middle-name":"","first-
name":"SIMONE"},"mar-stat":"M","sex":"F","birth":712981,"full-address":{"post-
code":"89300","address-line":["26 AVENUE RHIN ET 
DA"],"country":"F","city":"JOIGNY"},"telephone":{"area-
code":"1033","phone":"44864858"},"dept":"VENT59","job-title":"CHEF DE 
SERVICE","income":[{"curr-code":"EUR","bonus":[138],"salary":963}],"leave-
date":{"leave-taken":5,"leave-due":19},"leave-booked":[{"leave-start":19990801,"leave-
end":19990831}],"language":["FRE","ENG"]}]}

Note:
The Adabas REST Interface returns the long names of fields defined in a map.

The GET functionality is set up in advance to be used with query, search, and sort parameters, for example:

Request	Description
`GET http://localhost:8190/rest/map/EMPLOYEES-MAP?search=name=ADAM&descriptor=true`	Searches fields with the name 'ADAM' and returns the number of the records.
`GET http://localhost:8190/rest/map/EMPLOYEES- MAP/*/NAME?sorted_by=name`	Reads all NAME fields in the datamap and sorts the results alphabetically.
`GET http://localhost:8190/rest/map/EMPLOYEES-MAP?search=name=ADAM&fields=full-name,full-address&flatten=true`	Searches fields with the name 'ADAM' and returns flattened records of the full name and address.
`GET http://localhost:8190/rest/map/EMPLOYEES-MAP/*/NAME?limit=5&sorted_by=name&search=name>'CANALE'`	Reads all NAME fields for 'name' greater then 'CANALE' and returns an alphabetically sorted list of 5 records.
`GET http://localhost:8190/rest/map/EMPLOYEES-MAP/*/NAME?start=5&sorted_by=name&search=name>'CANALE'`	Reads all NAME fields for 'name' greater then 'CANALE' and returns an alphabetically sorted list. The result skips the first 5 records.

SEARCH

The HTTP SEARCH method defines the access to search data from the Adabas REST server.

You can perform the following types of queries:

With a direct search, you can search for a specific value. The values can be linked using the AND or OR keywords. You can also use <, >, or != in your queries. For example:
```
SEARCH
NAME<'SMITH' AND NUMBER<10
```
With a range search, you can search for a range that includes or excludes the first and last values in that range. The following example searches all strings beginning with SMITH up to Y, excluding Y.
```
SEARCH
PERSONELL_ID=['SMITH':'Y')
```
The values can be linked using the AND or OR keywords.
With a special search, you can search for results which include special characters. The following example searches for a super descriptor with 0x21 repeated at the end:
```
SEARCH
S2='BADABAS__'0x21*
S2=['BADABAS__'0:'BADABAS__'255]
S2=['BADABAS__'0x00:'BADABAS__'0xFF(10)]
S2=['BADABAS__'0x00:'BADABAS__'0xFFFFFFFFFFFFFFFFFFFF]
```

These search requests return JSON or XML data that looks as follows:

{"Records":[
    {"ISN":1,
    "personnnel-id":"50005800",
    "language":["FRE","ENG"]
    }
  ],
  "FileRecords":10,
  "NrRecords":1}

The result set may be limited by the limit search parameter.

PUT

The HTTP PUT method allows you to update data records on the Adabas REST server.

Use the Record tag to provide the input data. For example:

PUT 
http://host name/rest/map/map name 
{"Record":[{"ISN":1,"full-name":{"name":"ADAM","first-name":"SIMONES"}}]}

This request returns JSON data that looks as follows:

{"Store": [
    {"AA": "90003800",
      "AB": {         "AC": "THORSTEN",         "AD": "",         "AE": "WILLI"       },
      "AF": "W",
      "AG": "M",
    }
  ]
}

PUSH

The HTTP PUSH method allows you to insert data in data records on the Adabas REST server.

Use the Store tag to provide the input data. For example:

PUSH
http://host name/rest/map/map name
{"Store":[{"ISN":1,"full-name":{"name":"ADAM","first-name":"SIMONES"}}]}

This request returns JSON data that looks as follows:

{"Store": [
    {"AA": "90003800",
      "AB": {         "AC": "THORSTEN",         "AD": "",         "AE": "WILLI"       },
      "AF": "W",
      "AG": "M",
    }
  ]
}

DELETE

The HTTP Delete method deletes records from a database on the Adabas REST server. You must specify the ISN.

The request to delete data looks as follows:

DELETE
http://host name/rest/map/map name/isn

Example Application

The example subdirectory provides an example application to help you learn more about accessing Adabas using the REST interface.

Before you start the example application, prepare a database with the necessary files and mapping definitions:

Create a standard Adabas demo database with the crdemodb command, for example, crdemodb 4.
Load the example.bck backup file into the database. The backup file is located in the data subdirectory of the REST Interface installation. For example, use the following command sequence to load the backup file: adadbm db=4 delete=4-202, BCK001=example.bck, adabck db=4 restore=4-202). You must not renumber these files.

Create two mappings with the Data Designer: TestMapEmployee for file 11, and TestMapVehicle for file 12. The required mappings are:

TestMapEmployee

Adabas Field	Long Name
AA	ID
AC	FirstName
AE	LastName
AO	Department
AS	Salary
AT	Bonus

TestMapVehicle

Adabas Field	Long Name
AD	Vendor
AE	Model
AF	Color

Configure the REST Server in order to gain access to the database files and the mapping files.

Start the example application and choose the appropriate database. The example uses the DBID 24 as default. To select another database, click Select Demo Database. To change the default database ID, edit the index.html file accordingly.

The application shows the URL of your query and the result in JSON format. Click Rest Interface URL or Result to see all record metadata. Additionally, the example application contains a number of predefined JSON queries that request data from the database and show the results in the lower part of the window.

To make flexible requests, select the Free Form tab. For a demonstration of how the PUT and DELETE methods work, select the Modify Record tab.

Note:
The requests made through the example application do not modify the data in the database.