Objectivity REST : Getting Started With Objectivity REST : A Quick Tour
1 
A Quick Tour
In this topic you will:
Create a new federated database.
Start the rest server.
Get information from the server.
Add class descriptions to the federated database schema.
Create objects and perform queries.
Modify and delete objects.
Creating a Federated Database
With Objectivity/DB, you typically distribute related data in many individual databases (.DBs), which are members of a single federated database.
To create the federated database:
1. Create a data directory inside a project directory, for example, myProject/data.
2. Open a command prompt in the data directory and use an administrative tool to create a federated database named rentalFleet:
objy CreateFd -fdName rentalFleet
3. Examine the files created in the data directory.
rentalFleet.boot is the boot file for the new federated database. Applications interact with a federated database by accessing its boot file.
rentalFleet.fdb is the system database file. It maintains the global catalog of databases, the schema, indexes, and other internal information. Later, as objects are added to the federated database, additional database files will be created in the same location.
Now you are ready to use Objectivity REST to interact with the federated database.
Starting the REST Server
The Objectivity REST server executable is found in installDir/bin of your installation and is available in your path after a typical installation.
You start the server on the command line, providing at least a single option that identifies the boot file for the federated database to be hosted by the server. This topic assumes you are running the server on the local host.
To start the Objectivity REST server for the newly created federated database:
1. Still in the data directory, issue the following command:
objy StartRestServer -logDir . -bootFile ./rentalFleet.boot
The server creates a log file in the current directory (data) before starting. You can omit the -logDir option if you want the server to use the default log directory (installDir/logs/RESTServer).
objy StartRestServer -bootFile ./rentalFleet.boot
You must have write permissions to the log directory, or the REST server will not start.
The server uses port 8185 by default.
2. (Optional) Check that the REST server is running, then stop and restart the server:
objy CheckRestServer -port 8185
objy StopRestServer -port 8185
objy StartRestServer -bootFile ./rentalFleet.boot
To use a different port number or otherwise configure the server, see StartRESTServer in Objectivity/DB Administration.
Getting Information
In this section you will get information about the server and the connected federated database using curl.
Note: Even though curl does not format responses with line breaks and indentation, the responses shown in this documentation will be formatted for readability. Other REST tools such as Google Postman provide formatted responses.
To get information about the server and the resources of the federated database:
1. Request information about the server in JSON format:
curl -X GET -H "Accept:application/json" localhost:8185
The response shows the uptime of the server in milliseconds and lists available versions of the API.
{
  "uptime": 156497,
  "versions": [
    "v1"
  ]
}
Note: You can improve the readability of responses on Linux by using echo to include a newline, for example:
curl -X GET -H "Accept:application/json" localhost:8185 ;echo
2. Request a listing of all available resources:
curl -X GET -H "Accept:application/json" localhost:8185/v1
The response shows the URIs and the HTTP methods for each resource:
{
  "version": "v1",
  "resources": [
    {
      "uri": "/v1/fd",
      "supportedMethods": [
        "get"
      ]
    },
    {
      "uri": "/v1/tool",
      "supportedMethods": [
        "get",
        "post"
      ]
    },
    ...
Note: Information about the version of installed Objectivity software (different than the REST server version), the host running the lock server, the architecture on which the REST server is running, and other information can be found at the end of the output.
3. Get more information about the federated database (fd) resource:
curl -X GET -H "Accept:application/json" localhost:8185/v1/fd
The response provides the path name of the bootfile:
{ "bootfile": "rentalFleet.boot" }
4. Using the response from step 2 as a guide, get more information about other resources.
Adding Class Descriptions
Before adding objects to a federated database, you need to create class descriptions for those objects. Let’s add a class description for a Customer class to our federated database.
You create one or more class descriptions in a JSON array that is provided in the body of a POST request. The following shows a class description for the Customer class, which is part of the FleetData namespace. The Customer class has an isReferenceable label that is set to true, which means that objects of this class can be persistently stored in the federated database and can be referenced by other objects. The class has three attributes, an integer attribute and two string attributes.
[
  {
    "className": "FleetData.Customer",
    "isReferenceable": true,
    "superClass": null,
    "attributes": [
      {
        "attributeName": "rewardPoints",
        "logicalType": "integer",
        "encoding": "unsigned",
        "storage": "b32"
      },
      {
        "attributeName": "firstName",
        "logicalType": "string",
        "encoding": "utf8",
        "storage": "variable"
      },
      {
        "attributeName": "lastName",
        "logicalType": "string",
        "encoding": "utf8",
        "storage": "variable"
      }
    ]
  }
]
Note: For complete information about available types and their encoding and storage, see Objectivity/DB Data Types.
To add the Customer class description to the federated database:
1. Confirm that the federated database does not currently include class descriptions:
curl -X GET -H "Accept:application/json" localhost:8185/v1/schema
2. Copy and paste the above JSON into a file named Customer.txt in the data directory.
3. Post the class description as follows:
curl -X POST -H "Content-Type:application/json,Accept:application/json" -d @Customer.txt localhost:8185/v1/schema
The response provides the class number and URI of the new class, for example:
{
  "classNumbers": [
    "1000000"
  ],
  "uris": [
    "/v1/schema/1000000"
  ]
}
Creating Objects
Now that the Customer class description is available, you can create objects of that class. If you omit attributes when creating an instance, default values are used.
Recall that when using curl on the command line, you need to surround request bodies with single quotes (Linux) or double quotes (Windows), and you must escape double quotes inside the body with backslashes.
To create Customer objects:
1. Use a POST request that includes only the name of the class in the body:
curl -X POST -H "Content-Type:application/json,Accept:application/json" -d "{\"class\":\"FleetData.Customer\"}" localhost:8185/v1/object
The OID for the new object is included in the response:
{
  "__identifier__":"3-3-1-4",
  "uri":"/v1/object/3-3-1-4"
}
2. Access the representation of the new object by providing its OID in a GET request, for example:
curl -X GET --header "Accept:application/json" localhost:8185/v1/object/3-3-1-4
Note the default values supplied for the attributes in the response:
{
  "__class__": "FleetData.Customer",
  "__identifier__": "3-3-1-4",
  "rewardPoints": "0",
  "firstName": null,
  "lastName": null
}
Note that the GET output displays the OID of the object as the value of the label __identifier__.
3. Create a new object and supply values for the firstName and lastName attributes this time:
curl -X POST -H "Content-Type:application/json,Accept:application/json" -d "{\"class\":\"FleetData.Customer\",\"attributes\":{\"lastName\":\"Suarez\",\"firstName\":\"Mike\"}}" localhost:8185/v1/object
Note the OID for the new object.
4. Access the representation of the new object, for example:
curl -X GET --header "Accept:application/json" localhost:8185/v1/object/3-3-1-5
Note the values you supplied for the attributes:
{
  "__class__": "FleetData.Customer",
  "__identifier__": "3-3-1-5",
  "rewardPoints": "0",
  "firstName": "Mike",
  "lastName": "Suarez"
}
Querying for Objects
You can query for objects using the Declarative Objectivity (DO) Language. DO is a database language that supports queries, updates, and data ingest. You will be using the query functionality in this section.
You can query for all objects of a given class or you can narrow your search based on attribute values.
To query for objects created in the previous exercise:
1. Use the query resource to find all Customer objects:
curl -X POST -H "Content-Type:application/json,Accept:application/json" -d "{\"query\":\"FROM FleetData.Customer RETURN *;\",\"language\": \"do\"}" localhost:8185/v1/query
The response is a JSON array of the two found objects.
[
  {
    "__class__": "FleetData.Customer",
    "__identifier__": "3-3-1-4",
    "rewardPoints": "0",
    "firstName": null
    "lastName": null,
  },
  {
    "__class__": "FleetData.Customer",
    "__identifier__": "3-3-1-5",
    "rewardPoints": "0",
    "firstName": "Mike"
    "lastName": "Suarez",
  }
]
Note that the query output displays the OID of each found object as the value of the label __identifier__.
2. To query for only the customer whose first name is Mike:
curl -X POST -H "Content-Type:application/json,Accept:application/json" -d "{\"query\":\"FROM FleetData.Customer WHERE firstName='Mike' RETURN *;\",\"language\": \"do\"}" localhost:8185/v1/query
The response shows that one object is found, for example:
[
  {
    "__class__": "FleetData.Customer",
    "__identifier__": "3-3-1-5",
    "rewardPoints": "0",
    "firstName": "Mike",
    "lastName": "Suarez"
  }
]
3. Make a note of the OID (3-3-1-5) for the customer named Mike for use in the next exercise.
For more information about queries, see POST /v1/query.
For more information about the DO language, see Declarative Objectivity (DO) Language.
Modifying Objects
You can modify existing objects using a PUT operation. With a PUT operation, you provide one or more new values for attributes in the request body. You should omit attributes that are to remain unchanged to avoid the unnecessary overhead of overwriting a value with the same value.
To modify a Customer object and confirm your change:
1. Provide a new value for the firstName attribute of the Customer object returned by the query above. To specify the object, you use the OID returned by the query.
For example:
curl -X PUT -H "Content-Type:application/json,Accept:application/json" -d "{\"class\":\"FleetData.Customer\",\"attributes\":{\"firstName\":\"Michael\"}}" localhost:8185/v1/object/3-3-1-5
The value of the firstName attribute is changed from Mike to Michael.
2. Perform a query to confirm your change:
curl -X POST -H "Content-Type:application/json,Accept:application/json" -d "{\"query\":\"FROM FleetData.Customer WHERE firstName='Michael' RETURN *;\",\"language\": \"do\"}" localhost:8185/v1/query
The response indicates a single Customer named Michael is found. For example:
[
  {
    "__class__": "FleetData.Customer",
    "__identifier__": "3-3-1-5",
    "rewardPoints": "0",
    "firstName": "Michael",
    "lastName": "Suarez"
  }
]
Deleting Objects
To delete an existing object:
Provide the identifier of the object to delete as the end of the URI. For example:
curl -X DELETE -H "Accept:application/json" localhost:8185/v1/object/3-3-1-5
Next Steps
In the next exercise you will learn about creating objects that have relationships (references) to other objects. To do this, you will first update your federated database to include the complete schema from the sample rental fleet example. You will then add various objects to the federated database using a transaction resource that supports batch processing for REST requests. Finally, you will update the objects to provide the relationships between them.