1. Guide
  2. REST API in Oracle Spatial Studio

6 REST API in Oracle Spatial Studio

Oracle Spatial Studio provides a rich RESTful API that can be accessed not only from its web application user interface (UI), but also from the command line or programmatically from any other server or web applications.

Introduction

When you login to the Spatial Studio web application, the application UI is constantly sending and receiving application data using the REST API endpoints. The URLs to access the endpoints typically start with <studio-base-URL>/api/v1. The base URL is the entry point to Spatial Studio, such as https://localhost:4040/spatialstudio. When you first login to the Spatial Studio web application, the browser sends several AJAX requests to load various metadata from the server. The REST API endpoints are always in use by the web application when you perform different actions such as listing of the existing projects to which you have access, setting your various preferences, listing running tasks, and so on.

For instance, to get the detailed information about the currently logged in user, the web application sends an HTTP GET request to the URL: https://localhost:4040/spatialstudio/api/v1/user. This is provided the base URL is https://localhost:4040/spatialstudio. Although the response to such requests is typically in JSON format, there are other requests that return other types of data such as compressed vector tiles (when displaying geometry datasets on a map), or images (when displaying GeoRaster datasets).

The OpenAPI 3.0 specification for all the REST endpoints is available in the form of a YAML specification in Spatial Studio OpenAPI Specification for the REST API Endpoints. Note, however, many of the requests require a (sometimes quite complex) JSON payload, which are currently not part of the automatically generated OpenAPI YAML specification. This will be documented in a future release of Spatial Studio. Detailed description on the JSON request payload for the most common use cases are provided in the subsections of this chapter.

About Access Tokens

Apart from the Spatial Studio UI, almost all of the REST API endpoints can also be accessed from the command line using tools such as cURL, or from an external application programmatically. In both cases, you must first obtain an access token from Spatial Studio, as the token needs to be presented to the server. Also, when accessing the REST endpoints through an access token, the URLs will always start with the pattern <studio-base-URL>/oauth/v1. The only difference in the URL is that the path segment api is replaced with oauth. All other interaction behavior with the REST API endpoints from the Spatial Studio UI, external tools, or other applications remain the same.

An access token always includes the unique identity of the Spatial Studio user who generated the token. This user is considered the owner of the token. The owner identity is always verified when any REST endpoint is accessed through a token. See Generating an Access Token for the different types of access tokens that can be generated in Spatial Studio.

All the examples in the following subsections assume that you have obtained the proper type of access token. It is recommended you obtain the least privileged access token that will meet the requirements. For instance, a READ ONLY token is sufficient if you are not required to invoke a state-changing operation (such as deleting an analysis dataset). Similarly, if your requirement is only to consume and display your datasets in another mapping application, then consider using a Streaming-only access token, which cannot be used to query any other information from the server.

Note:

Generating Access Tokens Programmatically

About Access-Generator Tokens

Effective with Spatial Studio Release 23.2.1, you can create the access tokens programmatically without logging into the Spatial Studio UI. This allows better and safer management and distribution of access tokens, since these tokens are created only for short term usage, as and when needed by the application.

To programmatically create an access token, your application must first have an Access-Generator Token. It is a permanent token that is auto-created for each Spatial Studio user by the system. The purpose of this token is to create regular (but short-lived) access tokens which can be used to interact with Studio’s extensive set of REST APIs. The access-generator token itself cannot be used to invoke any of the Studio’s REST APIs (except the one that creates regular tokens).

See Copying the Access-Generator Token to obtain the access-generator token.

As the access-generator token is permanently associated with a valid Spatial Studio user, ensure the following:

  • Keep the token always secure. For instance, the token must not be exposed in the JavaScript code of a web page.
  • A typical workflow is to store and use the access-generator token in the backend of your application. Also, for each user session create a regular access token which can be used in your JavaScript code to interact with a Spatial Studio server as needed.

Also, the examples in the following sections assume that the Spatial Studio server is running and accessible at the URL https://localhost:4040/spatialstudio.