Objectivity REST : Getting Started With Objectivity REST
Getting Started With Objectivity REST
What is Objectivity REST?
Objectivity REST provides a server and a RESTful interface for accessing the resources of an Objectivity/DB federated database, which is the distributed graph data store provided with ThingSpan.
REST (REpresentational State Transfer) is a stateless architecture used to define web applications. REST uses a client-server model with a well defined interface that separates the concerns of the client from those of the application. Clients initiate requests using HTTP methods, and servers process those requests and return responses.
A REST request involves a particular resource, which is a basic abstraction of information for a given domain. Objectivity REST provides access to the resources of an Objectivity/DB federated database. These resources let you work with individual objects in the database, and also provide access to more global features such as indexing, query, database administration, and so forth.
The Objectivity REST server handles requests from any number of clients, takes appropriate action, and returns responses.
Any of the various third-party tools for sending HTTP REST requests can be used with Objectivity REST. Most of the examples in the documentation use curl, but you can use whichever tools you prefer.
A Typical Objectivity REST Request
Let’s take a look at an Objectivity REST request that creates a Customer object in the federated database.
In REST, a POST HTTP method is what you use to create a new entity. A POST operation typically includes a request body, which provides the details needed to create the object. For our Customer object, the body must specify the class of object to create and can optionally provide values for any attributes.
The base URL specifies the HTTP address and port number where the server is handling requests.
The base URL is followed by the version number (v1) and the targeted resource (object). The version number and the resource together form the unique resource identifier (URI), which is also known as an endpoint. A single URI often provides access to multiple operations.
Two headers are provided as part of the request. One specifies the format of the request body, and the other specifies the desired format for the server’s response. Both are set to JSON, which is the supported format in Objectivity REST.
Assuming that the REST server is running on the local host at port 6784, the request above creates a new Customer object with a value of 65 for the rewardPoints attribute.
About Resources
A single URI can provide access to multiple operations. For example, Objectivity REST has a /v1/object/{oid} URI that identifies a particular object in the federated database by its object identifier or OID. You can use GET, PUT, or DELETE HTTP methods on this URI to perform different actions on the given object.
How to Send REST Requests
There are various third-party tools for sending REST requests, but two common ones are curl/libcurl and the Google Postman app.
Using Curl
Curl is a popular, open-source command-line tool that sends HTTP requests and provides responses. For example, the following curl command gets information about the object with the given OID in the federated database.
curl -X GET -H "Accept:application/json" localhost:8185/v1/object/1125904202006531
The -X option precedes the HTTP method to use, and -H precedes the headers; see https://curl.haxx.se/ for more information about curl.
With curl, the server responses are compact, which may or may not be desirable.
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
Using Google Postman
Postman provides an intuitive GUI for sending REST requests and receving responses. You use a menu to choose the HTTP method, then supply the appropriate URI in a text entry field. Below this is a Body tab for entering JSON bodies and a Headers tab for specifying REST headers.
An advantage of using Postman is that the server responses are formatted for readability.
Providing Request Bodies
Operations that use POST and PUT methods typically require that you supply information in the body of the request.
Using Curl
When using curl to submit a request, you can provide the body directly on the command line or in a file.
When providing the body on the command line, you must escape double quotes with backslashes. In addition, be aware that Windows and Linux platforms require different syntax for surrounding the body—use single quotes on Linux, double quotes on Windows.
Linux
'{\"class\":\"FleetData.Customer\",\"attributes\":{\"rewardPoints\":\"99\"}}'
Windows
"{\"class\":\"FleetData.Customer\",\"attributes\":{\"rewardPoints\":\"99\"}}"
Using a file is easier when the body is long. You can use formatting to see the organization of information, and you don’t need to escape double quotes. For example, the following body that creates a Customer object in the FleetData namespace can be included in a file named myCustomerFile.txt.
 
{ 
  "class": "FleetData.Customer",
  "attributes":
    { 
      "firstName": "Louis",
      "lastName": "Richardson",
      "rewardPoints": "65"
    }
} 
A curl command can then designate this file using the -d option, as follows:
curl -X POST -H "Content-Type:application/json,Accept:application/json" -d @myCustomerFile.txt localhost:8185/v1/object
Using Postman
Postman provides text-input fields for the bodies of PUT and POST operations (use the raw format).
Learn More
You can obtain an overview of Objectivity REST capabilities by continuing with the following topics:
A Quick Tour
Working with Relationships
For further details, explore these topics:
API Summary
Objectivity/DB Data Types.
You can inspect the complete schema for a sample application (a fleet rental company) that is referred to often throughout this documentation.