1. Guide
  2. REST API in Oracle Spatial Studio

4 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 Appendix A. 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.

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