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
.
- Using cURL with Spatial Studio REST APIs
cURL
is a powerful command line tool available on many platforms for sending and receiving URL requests to a remote server. - Accessing Spatial Studio REST API Programmatically
You can programmatically interact with the Spatial Studio REST API endpoints from another application.