MySQL REST Service - SQL Reference

#
MySQL REST Service - SQL Reference

This document discusses the MySQL REST Service (MRS) DDL - SQL Extension. The MRS DDL - SQL Extension adds a set of MRS specific DDL statements to the MySQL Shell SQL handling in order to provide a familiar management interface to MySQL developers and DBAs.

Chapter Overview

- Introduction to the MRS DDL Extension
- MRS SQL Reference: CONFIGURE and CREATE
- MRS SQL Reference: ALTER
- MRS SQL Reference: DROP
- MRS SQL Reference: GRANT and REVOKE
- MRS SQL Reference: USE and SHOW

Please also see

- MySQL REST Service - Developer’s Guide - This book explains how to install and configure the MySQL REST Service (MRS) as well as how to access the data through REST calls.
- MySQL REST Service - Quickstart Guide - This book provides a hands-on approach to learning how to use the MySQL REST service.
- MySQL REST Service - Core REST APIs - This book provides examples of using the MySQL REST Service queries and other operations against tables and views after you have REST-enabled them.
- MySQL REST Service - SDK Reference - This book explains how to work with the MRS Software Development Kit and discusses the Client APIs.

# 1 Introduction

It has been an essential goal of the MySQL REST Service (MRS) to provide a management interface that feels familiar to MySQL developers and DBAs and integrates well into their existing processes.

For this purpose the MySQL REST Service plugins directly into the MySQL Shell and MySQL Shell for VS Code. It extends the available SQL commands to include DDL (Data Definition Language) statements that allow managing the MySQL REST Service in an easy and seamless way.

This makes the process of creating a MySQL REST Service for your application as easy as creating a database schema or table.

Example

The following script configures the MySQL REST Service, creates a new REST service `/myService` and adds a REST schema `/sakila` and a REST data mapping view `/actor` that lists all actors and their film titles.

    CONFIGURE REST METADATA;

    CREATE REST SERVICE /myService;
    USE REST SERVICE /myService;

    CREATE REST SCHEMA /sakila FROM `sakila`;
    USE REST SCHEMA /sakila;

    CREATE REST VIEW /actor
    AS `sakila`.`actor` {
        actorId: actor_id @SORTABLE,
        firstName: first_name,
        lastName: last_name,
        lastUpdate: last_update,
        filmActor: sakila.film_actor @UNNEST {
            film: sakila.film @UNNEST {
                title: title
            }
        }
    }
    AUTHENTICATION REQUIRED;

> Note: Please ensure to install the MySQL sakila example database schema before running the MRS DDL script above.

# 2 CONFIGURE and CREATE

## 2.1 CONFIGURE REST METADATA

The CONFIGURE REST METADATA statement is used to perform the initial configuration of the MySQL REST Service on a MySQL Server instance or InnoDB Cluster/Set.

It will create the `mysql_rest_service_metadata` database schema.

Please note that the MySQL account used to execute the statement needs the required privileges to create database schemas.

Syntax

    configureRestMetadataStatement:
        CONFIGURE REST METADATA restMetadataOptions?
    ;

    restMetadataOptions: (
            enabledDisabled
            | jsonOptions
            | updateIfAvailable
        )+
    ;

configureRestMetadataStatement ::=

restMetadataOptions ::=

Example

    CONFIGURE REST METADATA;

### 2.1.1 Enable or Disable the MySQL REST Service

The enabledDisabled option specifies if the MySQL REST Service should be enabled or disabled after the configuration operation. The default is set to enable the MySQL REST Service.

    enabledDisabled:
        ENABLED
        | DISABLED
    ;

enabledDisabled ::=

Examples

The following example configures the MySQL REST Service and enables it and updates the metadata schema, if possible.

    CONFIGURE REST METADATA
        ENABLED
        UPDATE IF AVAILABLE;

The following example configures the MySQL REST Service and enables the GTID cache and sets authentication options.

    CONFIGURE REST METADATA
        ENABLED
        OPTIONS {
            "gtid": {
                "cache": {
                    "enable": true,
                    "refreshRate": 5,
                    "refreshWhenIncreasesBy": 500
                }
            },
            "authentication": {
                "throttling": {
                    "perAccount": {
                        "minimumTimeBetweenRequestsInMs": 1500,
                        "maximumAttemptsPerMinute": 5
                    },
                    "perHost": {
                        "minimumTimeBetweenRequestsInMs": 1500,
                        "maximumAttemptsPerMinute": 5
                    },
                    "blockWhenAttemptsExceededInSeconds": 120
                }
            }
        };

### 2.1.2 REST Configuration Json Options

The jsonOptions allow to set a number of specific options for the MySQL REST Service. Specify the `MERGE` keyword to merge the given options with the existing options. If `MERGE` is omitted, all existing options will be overwritten with the specified options.

    jsonOptions:
        MERGE? OPTIONS jsonValue
    ;

jsonOptions ::=

These options can include the following JSON keys.

- `authentication`
  - Defines global authentication parameters valid for all MySQL Routers
  - `throttling`
    - Used to limit the authentication attempts to prevent brute force attacks on account information
    - `perAccount`
      - Settings that apply per MRS account
      - `minimumTimeBetweenRequestsInMs`
        - Sets the minimum time between connection attempts. If a client tries to authenticate faster than that the request will be rejected. The value is given in milliseconds.
      - `maximumAttemptsPerMinute`
        - Sets the maximum amount of attempts per minute. If a client tries to authenticate more often that that further attempts will be blocked for the amount of seconds specified in the `blockWhenAttemptsExceededInSeconds` value.
    - `perHost`
      - Settings that apply per host from where a client tries to connect
      - `minimumTimeBetweenRequestsInMs`
      - `maximumAttemptsPerMinute`
    - `blockWhenAttemptsExceededInSeconds`
      - Sets the amount of time the account or client host will be blocked from authentication. The value is given in seconds.
- `gtid`
  - Defines global settings for the MySQL GTID handling, using the following fields.
  - `cache`
    - Is used to configure the MySQL Router’s GTID cache.
    - `enable`
      - If set to `true` GTIDs will be cached by the MySQL Router.
    - `refreshRate`
      - Defines how often the GTID cache will be refreshed. Set seconds, e.g. 5.
    - `refreshWhenIncreasesBy`
      - In addition to the time based refresh, the GTID cache can also be refreshed based on the number of transactions that happened since the last refresh. Set in number of transactions, e.g. 500.
- `responseCache`
  - Global options for the REST endpoint response cache, which keeps an in-memory cache of responses to GET requests on tables, views, procedures and functions. To enable caching of an endpoint, you must also set the `cacheTimeToLive` option for each object to be cached.
  - `maxCacheSize`
    - Maximum size of the cache. Default is 1M.
- `fileCache`
  - Global options for the static file data cache, which keeps an in-memory cache of responses to GET requests on content set files.
  - `maxCacheSize`
    - Maximum size of the cache. Default is 1M.
- `defaultStaticContent`
  - Allows the definition of static content for the root path `/` that will be returned for file paths matching the given JSON keys. A JSON key `index.html` will be served as `/index.html` by the MySQL Router. The file content needs to be Base64 encoded. If the same JSON key is used for `defaultStaticContent` as well as for `defaultRedirects`, the redirect is prioritized.
- `defaultRedirects`
  - Is used to define internal redirects performed by the MySQL Router. This can be used to expose content of a REST service on the root path `/`. A JSON key `index.html` holding the value `/myService/myContentSet/index.html` will exposed the corresponding file from the given path as `/index.html`.
- `directoryIndexDirective`
  - Holds an ordered list of files that should be returned when a directory path has been requested. The first matching file that is available will be returned. The `directoryIndexDirective` is recursively applies to all directory paths exposed by the MySQL Router. To change the `directoryIndexDirective` for a given REST service or REST static content set, the corresponding option needs to be set for those objects.

All other keys will be ignored and can be used to store custom metadata about the service. It is a good practice to include a unique prefix when adding custom keys to avoid them be overwritten by future MRS options.

Examples

The following JsonValue will define the static content for `/index.html`, `/favicon.ico` and `/favicon.svg`. It will also direct the MySQL Router to return the contents of `/index.html` if the root path `/` is requested, e.g. `https://my.example.com/`

    {
        "defaultStaticContent": {
            "index.html": "PCFET0NUW...",
            "favicon.ico": "AAABAAMAM...",
            "favicon.svg": "PD94bWwmV..."
        },
        "directoryIndexDirective": [
            "index.html"
        ]
    }

In this example an internal redirect of `/index.html` to `/myService/myContentSet/index.html` is performed, directly serving the `index.html` page of `/myService/myContentSet`. This overwrites the `index.html` definition in `defaultStaticContent`.

This is useful to directly serve a specific app on the root path `/`.

    {
        "defaultStaticContent": {
            "index.html": "PCFET0NUW...",
            "favicon.ico": "AAABAAMAM...",
            "favicon.svg": "PD94bWwmV..."
        },
        "defaultRedirects": {
            "index.html": "/myService/myContentSet/index.html"
        },
        "directoryIndexDirective": [
            "index.html"
        ]
    }

### 2.1.3 Updating the MySQL REST Service Metadata Schema

If the updateIfAvailable is defined, the configure operation will include an update of the `mysql_rest_service_metadata` database schema.

    updateIfAvailable:
        UPDATE (IF AVAILABLE)?
    ;

updateIfAvailable ::=

## 2.2 CREATE REST SERVICE

The CREATE REST SERVICE statement is used to create a new or replace an existing REST service.

The MySQL REST Service supports the creation of many individual REST services. It is good practice to create a separate REST service for each REST application.

Each REST service can have its own options, authentication apps and supports a different set of authentication users.

Please note that service will not be published at creation time by default. They will only be served by MySQL Routers that are bootstrapped for development purposes. To publish a REST service after all REST schemas and REST objects have been created please use the `ALTER REST SERVICE` statement and set the PUBLISHED option.

SYNTAX

    createRestServiceStatement:    (
            CREATE OR REPLACE REST SERVICE
            | CREATE REST SERVICE (
                IF NOT EXISTS
            )?
        ) serviceRequestPath restServiceOptions?
    ;

    serviceRequestPath:
        serviceDevelopersIdentifier? requestPathIdentifier
    ;

    restServiceOptions: (
            enabledDisabled
            | publishedUnpublished
            | restProtocol
            | restAuthentication
            | jsonOptions
            | comments
            | metadata
            | addAuthApp
            | removeAuthApp
        )+
    ;

createRestServiceStatement ::=

serviceRequestPath ::=

restServiceOptions ::=

Examples

The following example creates a REST service `/myService`. Please note that you need to set the `PUBLISHED` option to make the REST service publicly available.

    CREATE OR REPLACE REST SERVICE /myService
        COMMENT "A simple REST service";

The next example shows how to set the REST service options.

    CREATE OR REPLACE REST SERVICE /myTestService
        COMMENTS "A simple REST service"
        AUTHENTICATION
            PATH "/authentication"
            REDIRECTION DEFAULT
            VALIDATION DEFAULT
            PAGE CONTENT DEFAULT
        OPTIONS {
            "headers": {
                "Access-Control-Allow-Credentials": "true",
                "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Requested-With, Origin, X-Auth-Token",
                "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS"
            },
            "http": {
                "allowedOrigin": "auto"
            },
            "logging": {
                "exceptions": true,
                "request": {
                    "body": true,
                    "headers": true
                },
                "response": {
                    "body": true,
                    "headers": true
                }
            },
            "returnInternalErrorDetails": true,
            "includeLinksInResults": false
        };

### 2.2.1 Building a ServiceRequestPath

When creating or accessing a REST service a `serviceRequestPath` has to be specified which uniquely identifies the REST service across the MySQL REST Service.

It consists of three components.

- `serviceDevelopersIdentifier` (optional) - When set, the REST service is only available to the developers listed.
- `requestPathIdentifier` - The URL context root path the REST service will be served from.

In many cases setting the `requestPathIdentifier` will be sufficient.

The `serviceDevelopersIdentifier` will be set automatically when a REST service is cloned for development by a given developer. Should such a REST service be made available to more developers, the list of developers can be extended via an `ALTER REST SERVICE` command.

    serviceDevelopersIdentifier:
        serviceDeveloperIdentifier (
            COMMA serviceDeveloperIdentifier
        )* AT_SIGN
    ;

    requestPathIdentifier:
        REST_REQUEST_PATH
        | BACK_TICK_QUOTED_ID
        | {if AnsiQuotes} DOUBLE_QUOTED_TEXT
    ;

serviceDevelopersIdentifier ::=

requestPathIdentifier ::=

### 2.2.2 Enabling or Disabling a REST Service at Creation Time

The `enabledDisabled` option specifies whether the REST service should be enabled or disabled. REST services are created in the ENABLED state by default. The state can be changed via the `ALTER REST SERVICE` statement.

Please also see the `publishedUnpublished` option which determines if a REST service is served by MySQL Routers.

    enabledDisabled:
        ENABLED
        | DISABLED
    ;

enabledDisabled ::=

### 2.2.3 Publishing a REST Service at Creation Time

The `publishedUnpublished` option specifies whether the REST service should be in `PUBLISHED` or `UNPUBLISHED` state. REST services are created in the `UNPUBLISHED` state by default.

A REST service in `UNPUBLISHED` state will only be served by MySQL Routers that are bootstrapped for development using the `--mrs-development <user>` option. To make a REST service publicly available on all MySQL Routers it needs to be set to the `PUBLISHED` state using the `ALTER REST SERVICE` statement.

    publishedUnpublished:
        PUBLISHED
        | UNPUBLISHED
    ;

publishedUnpublished ::=

### 2.2.4 Setting the REST Service Protocol

In general it is advised to run the MySQL REST Service using HTTPS only and changing the REST service protocol default (HTTPS) is not required.

There might still be special use cases when configuring the MySQL Router using HTTP is acceptable, e.g. when using a reverse proxy on the same machine that is handling the HTTPS part and not using MySQL internal authentication which requires passwords to be transferred in plain text. But even in that specific example the REST service protocol must be set to HTTPS as the reverse proxy offers the REST service via HTTPS.

Should there still be a configuration setup that requires the REST service to be accessible by clients via HTTP, the REST service protocol can be switched to HTTP.

This setting is used in one place.

- When performing an OAuth2 authentication request, the protocol is used to build the redirect URL parameter in the first authentication request to the OAuth2 server. The protocol used in the redirect URL parameter must match the external protocol the REST service is reachable on. In case of using a reverse proxy, the `X-Forwarded-Proto` request header will overwrite this setting when made available by the proxy.

    restProtocol:
        PROTOCOL (HTTP | HTTPS)
    ;

### 2.2.5 Assigning a REST Authentication App to a REST Service

To enable authentication for a REST service, a REST authentication app needs to be linked to the REST service. REST authentication apps are created using the CREATE REST AUTH APP statement.

REST authentication apps can be linked while creating the REST service or they can be added alter using the ALTER REST SERVICE statement.

    addAuthApp:
        ADD AUTH APP authAppName (IF EXISTS)?
    ;

addAuthApp ::=

### 2.2.6 REST Service Authentication Settings

Each REST service can be configured with specific authentication settings.

    restAuthentication:
        AUTHENTICATION (
            authPath
            | authRedirection
            | authValidation
            | authPageContent
        )*
    ;

    authPath:
        PATH quotedTextOrDefault
    ;

    authRedirection:
        REDIRECTION quotedTextOrDefault
    ;

    authValidation:
        VALIDATION quotedTextOrDefault
    ;

    authPageContent:
        PAGE CONTENT quotedTextOrDefault
    ;

restAuthentication ::=

authPath ::=

authRedirection ::=

authValidation ::=

authPageContent ::=

- AUTHENTICATION PATH
  - The html path used for authentication handling for this REST service. Specified as a sub-path to the REST service path. If not explicitly set, the default is path is `/authentication` is used.
  - The following endpoints will be made available for `<service_path>/<auth_path>`
    - `/login`
    - `/status`
    - `/logout`
    - `/completed`
- AUTHENTICATION REDIRECTION
  - The authentication workflow will redirect to this URL after successful- or failed login. Specified as a sub-path to the REST service path. If this option is not set explicitly, the workflow will redirect to `<service_path>/<auth_path>/completed` if the `<service_path>/<auth_path>/login?onCompletionRedirect` parameter has not been set.
- AUTHENTICATION VALIDATION
  - A regular expression to validate the `<service_path>/<auth_path>/login?onCompletionRedirect` parameter. If set, this allows to limit the possible URLs an application can specify for this parameter.
- AUTHENTICATION PAGE CONTENT
  - If this option is set its content will replace the page content of the `<service_path>/<auth_path>/completed` page.

### 2.2.7 REST Service Json Options

The jsonOptions allow to set a number of specific options for the service. Specify the `MERGE` keyword to merge the given options with the existing options. If `MERGE` is omitted, all existing options will be overwritten with the specified options.

    jsonOptions:
        MERGE? OPTIONS jsonValue
    ;

    jsonOptions ::=
    ![jsonOptions](../../images/sql/jsonOptions.svg "jsonOptions")

    These options can include the following JSON keys.

    - `headers` - Allows the specification of HTTP headers. Please refer to the HTTP header documentation for details.
    - `http`
      - `allowedOrigin` - The setting for Access-Control-Allow-Origin HTTP header. Can either be set to `*`, `null`, `<origin>` or `auto`. When set to `auto`, the MySQL Routers will return the origin of the specific client making the request.
    - `httpMethodsAllowedForUnauthorizedAccess` - If a REST objects is configured to not require authentication, only GET is allowed by default. In a testing environment it might be desirable to allow all HTTP methods. In that case this option can be set to a list of allowed methods, e.g. ["GET", "POST", "PUT", "DELETE"]
    - `logging`
      - `exceptions` - If exceptions should be logged.
      - `requests`
        - `body` - If the content of request bodies should be logged.
        - `headers` - If the content of request headers should be logged.
      - `response`
        - `body` - If the content of response bodies should be logged.
        - `headers` - If the content of response headers should be logged.
    - `returnInternalErrorDetails` - If internal errors should be returned. This is useful for application development but should be turned off for production deployments.
    - `includeLinksInResults` - If set to false, the results do not include navigation links.
    - `defaultStaticContent` - Allows the definition of static content for `request path` of the REST service that will be returned for file paths matching the given JSON keys. A JSON key `index.html` will be served as `/myService/index.html` by the MySQL Router if the `request path` of the REST service has been set to `/myService`. The file content needs to be Base64 encoded. If the same JSON key is used for `defaultStaticContent` as well as for `defaultRedirects`, the redirect is prioritized.
    - `defaultRedirects` - Is used to define internal redirects performed by the MySQL Router. This can be used to expose content on the `request path` of the of a REST service. A JSON key `index.html` holding the value `/myService/myContentSet/index.html` will exposed the corresponding file from the given path as `/myService/index.html` if the `request path` of the REST service has been set to `/myService`.
    - `directoryIndexDirective` - Holds an ordered list of files that should be returned when a directory path has been requested. The first matching file that is available will be returned. The `directoryIndexDirective` is recursively applies to all directory paths exposed by the MySQL Router. To change the `directoryIndexDirective` for a given REST object, the corresponding option needs to be set for that object.
    - `sqlQuery`
      - `timeout`
        - Number of milliseconds to allow for DB operations while serving an endpoint. DB requests taking longer than that time will be interrupted and an error 504 returned. Default 2000. Can be overridden at a per-endpoint basis.

    All other keys will be ignored and can be used to store custom metadata about the service. It is a good practice to include a unique prefix when adding custom keys to avoid them be overwritten by future MRS options.

    **_Examples_**

    ```json
    {
        "headers": {
            "Access-Control-Allow-Credentials": "true",
            "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Requested-With, Origin, X-Auth-Token",
            "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS"
        },
        "http": {
            "allowedOrigin": "auto"
        },
        "logging": {
            "exceptions": true,
            "request": {
                "body": true,
                "headers": true
            },
            "response": {
                "body": true,
                "headers": true
            }
        },
        "returnInternalErrorDetails": true,
        "includeLinksInResults": false
    }

### 2.2.8 REST Service Comments

The comments can hold a description of the REST service. The maximal length is of the comments string is 512 characters.

    comments:
        COMMENT textStringLiteral
    ;

comments ::=

### 2.2.9 REST Service Metadata

The metadata can hold any JSON data. It can later be consumed by a front end implementation to dynamically render certain attributes, like a specific icon or a color.

    metadata:
        METADATA jsonValue
    ;

## 2.3 CLONE REST SERVICE

Duplicates the contents of a REST service to a newly created one.

All endpoints and roles belonging to the given service are copied.

SYNTAX

    cloneRestServiceStatement:
        CLONE REST SERVICE serviceRequestPath NEW REQUEST PATH
            newServiceRequestPath
    ;

cloneRestServiceStatement ::=

## 2.4 CREATE REST SCHEMA

The CREATE REST SCHEMA statement is used to create a new or replace an existing REST schema. Each REST schema directly maps to a database schema and allows the database schema objects (tables, views and stored procedures) to be exposed via REST endpoints.

> Note: Adding a REST schema to a REST service does not automatically expose any database schema objects via REST. The corresponding `CREATE REST DATA MAPPING VIEW`, `CREATE REST PROCEDURE`, `CREATE REST FUNCTION` ddl commands need to be called to explicitly expose a database schema object.

Each REST schema belongs to a REST service, which has to be created first. One REST service can hold many REST schemas.

Each REST schema can have its own options, authentication apps and supports a different set of authentication users.

SYNTAX

    createRestSchemaStatement:    (
            CREATE OR REPLACE REST SCHEMA
            | CREATE REST SCHEMA (
                IF NOT EXISTS
            )?
        ) schemaRequestPath? (
            ON SERVICE? serviceRequestPath
        )? FROM schemaName restSchemaOptions?
    ;

    restSchemaOptions: (
            enabledDisabledPrivate
            | authenticationRequired
            | itemsPerPage
            | jsonOptions
            | comments
            | metadata
        )+
    ;

createRestSchemaStatement ::=

restSchemaOptions ::=

Examples

The following example creates a REST schema `/sakila` on the REST service `/myService`.

    CREATE OR REPLACE REST SCHEMA /sakila ON SERVICE /myService
        FROM `sakila`
        COMMENT "The sakila schema";

### 2.4.1 Enabling or Disabling a REST Schema at Creation Time

The `enabledDisabledPrivate` option specifies whether the REST schema should be enabled, disabled or private when it is created.

Setting a schema to private disables public access via HTTPS but keeps the schema available for private access from MRS scripts.

    enabledDisabledPrivate:
        ENABLED
        | DISABLED
        | PRIVATE
    ;

enabledDisabledPrivate ::=

### 2.4.2 Specifying the Default Page Count

The `itemsPerPage` option can be used to specify the default number of items returned for queries run against this REST schema.

    itemsPerPage:
        ITEMS PER PAGE itemsPerPageNumber
    ;

itemsPerPage ::=

The number of items per page can also be specified for each REST object individually.

### 2.4.3 REST Schema Json Options

The jsonOptions allow to set a number of specific options for the schema. Specify the `MERGE` keyword to merge the given options with the existing options. If `MERGE` is omitted, all existing options will be overwritten with the specified options.

    jsonOptions:
        MERGE? OPTIONS jsonValue
    ;

    jsonOptions ::=
    ![jsonOptions](../../images/sql/jsonOptions.svg "jsonOptions")

    These options can include the following JSON keys.

    - `defaultStaticContent` - This option serves the same purpose as described in the [REST Configuration Json Options](#rest-configuration-json-options).
    - `defaultRedirects` - This option serves the same purpose as described in the [REST Configuration Json Options](#rest-configuration-json-options).
    - `directoryIndexDirective` - This option serves the same purpose as described in the [REST Configuration Json Options](#rest-configuration-json-options).
    - `sqlQuery` - see [REST Service JSON Options](#rest-service-json-options)

    All other keys will be ignored and can be used to store custom metadata about the schema. It is a good practice to include a unique prefix when adding custom keys to avoid them be overwritten by future MRS options.

    ### REST Schema Comments

    The comments can hold a description of the REST schema. The maximal length is of the comments string is 512 characters.

    ```antlr
    comments:
        COMMENT textStringLiteral
    ;

comments ::=

### 2.4.4 REST Schema Metadata

The metadata can hold any JSON data. It can later be consumed by a front end implementation to dynamically render certain attributes, like a specific icon or a color.

    metadata:
        METADATA jsonValue
    ;

## 2.5 CREATE REST VIEW

The `CREATE REST DATA MAPPING VIEW` statement is used to add REST endpoints for database schema tables or views. Their data will be served as JSON documents.

The structure of the served JSON documents is defined using an extended GraphQL syntax. This allows to define even complex REST data mapping views in a simple and human readable way. Please see the corresponding GraphQL section about how to design the GraphQL definition for a REST data mapping view.

Please see the MRS Reference Manual to learn more about JSON data mapping views.

SYNTAX

    createRestViewStatement:    (
            CREATE OR REPLACE REST DATA? MAPPING? VIEW
            | CREATE REST DATA? MAPPING? VIEW (
                IF NOT EXISTS
            )?
        ) viewRequestPath (ON serviceSchemaSelector)? AS qualifiedIdentifier (
            CLASS restObjectName
        )? graphQlCrudOptions? graphQlObj? restObjectOptions?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

    restObjectOptions: (
            enabledDisabledPrivate
            | authenticationRequired
            | itemsPerPage
            | jsonOptions
            | comments
            | metadata
            | restViewMediaType
            | restViewFormat
            | restViewAuthenticationProcedure
        )+
    ;

createRestViewStatement ::=

serviceSchemaSelector ::=

restObjectOptions ::=

Examples

The following example adds a REST data mapping view for the `sakila.city` database schema table.

    CREATE REST VIEW /city
    ON SERVICE /myService SCHEMA /sakila
    AS `sakila`.`city` {
        cityId: city_id @SORTABLE,
        city: city,
        countryId: country_id,
        lastUpdate: last_update
    }
    AUTHENTICATION REQUIRED;

Querying the REST data mapping view using the TypeScript SDK returns the following JSON document.

    ts> myService.sakila.city.findFirst();
    {
       "city": "A Corua (La Corua)",
       "links": [
          {
             "rel": "self",
             "href": "/myService/sakila/city/1"
          }
       ],
       "cityId": 1,
       "countryId": 87,
       "lastUpdate": "2006-02-15 04:45:25.000000",
       "_metadata": {
          "etag": "EE93452B41984F3F5BBB0395CCB2CED00F5C748FEEA4A36CCD749CC3F85B7CEA"
       }
    }

The next example adds the referenced table `sakila.country` to the REST data mapping view.

    CREATE OR REPLACE REST VIEW /city
    ON SERVICE /myService SCHEMA /sakila
    AS `sakila`.`city` {
        cityId: city_id @SORTABLE,
        city: city,
        countryId: country_id,
        lastUpdate: last_update,
        country: sakila.country {
            countryId: country_id @SORTABLE,
            country: country,
            lastUpdate: last_update
        }
    }
    AUTHENTICATION REQUIRED;

This is what the REST data mapping view looks like in the interactive MySQL REST Object Dialog in the MySQL Shell for VS Code extension.

ı

Running a TypeScript SDK query against this new REST endpoint returns the following JSON Document.

    ts> myService.sakila.city.findFirst();
    {
        "city": "A Corua (La Corua)",
        "links": [
            {
                "rel": "self",
                "href": "/myService/sakila/city/1"
            }
        ],
        "cityId": 1,
        "country": {
            "country": "Spain",
            "countryId": 87,
            "lastUpdate": "2006-02-15 04:44:00.000000"
        },
        "countryId": 87,
        "lastUpdate": "2006-02-15 04:45:25.000000",
        "_metadata": {
            "etag": "FFA2187AD4B98DF48EC40B3E807E0561A71D02C2F4F5A3B953AA6CB6E41CAD16"
        }
    }

### 2.5.1 Preconditions

You define a REST data mapping view against a set of tables related by primary key (PK), foreign key (FK) or unique key constraints (UK). The following rules apply:

- The constraints must be declared in the database.
- The relationships type can be 1-to-1, 1-to-N and N-to-M (using a mapping table with two FKs). The N-to-M relationship can be thought of as the combination of 1-to-N and 1-to-1 relationship
- Columns of two or more tables with 1-to-1 or N-to-1 relationships can be merged into the same JSON object via UNNEST. Otherwise a nested JSON object is created.
- Tables with a 1-to-N relationship create a nested JSON array.
- Each item in the data mapping view is one JSON object, which is typically a hierarchy of nested objects and arrays.
- Each application object is built from values originating from one or multiple rows from the underlying tables of that view. Typically, each table contributes to one (nested) JSON object.

### 2.5.2 Enabling or Disabling a REST View at Creation Time

The `enabledDisabledPrivate` option specifies whether the REST data mapping view should be enabled, disabled or private when it is created.

Setting a REST data mapping view to private disables public access via HTTPS but keeps the schema available for private access from MRS scripts.

    enabledDisabledPrivate:
        ENABLED
        | DISABLED
        | PRIVATE
    ;

enabledDisabledPrivate ::=

### 2.5.3 Requiring Authentication for REST Views

The `authenticationRequired` option specifies if a REST data mapping view requires authentication before accessing its REST endpoints.

    authenticationRequired:
        AUTHENTICATION NOT? REQUIRED
    ;

authenticationRequired ::=

### 2.5.4 Specifying the Page Count for REST Views

The `itemsPerPage` option can be used to specify the number of items returned for queries run against the REST data mapping view.

    itemsPerPage:
        ITEMS PER PAGE itemsPerPageNumber
    ;

itemsPerPage ::=

The number of items per page can also be specified for each REST object individually.

### 2.5.5 Setting the Media Type for REST Views

If this REST data mapping view returns a specific MIME type it can be set via the `restViewMediaType` option. If MRS should try to automatically detect the file type based on the content of the file the `AUTODETECT` option can be used.

    restViewMediaType:
        MEDIA TYPE (
            textStringLiteral
            | AUTODETECT
        )
    ;

restViewMediaType ::=

### 2.5.6 Setting the Result Format for REST Views

A REST data mapping view can return one of the following formats which can be set with the `restViewFormat` option.

- FEED: A list of result JSON objects
- ITEM: A single result item
- MEDIA: A single blob item. The `restViewMediaType` option is used to set the corresponding MIME type in this case.

    restViewFormat:
        FORMAT (FEED | ITEM | MEDIA)
    ;

restViewFormat ::=

### 2.5.7 Using a Custom Authentication Procedure for a REST View

In case the built in authentication handling does not cover the specific use case for a REST data mapping view, a custom MySQL stored procedure can be used to handle the authentication check for the given user and the requested CRUD operation.

The referenced MySQL stored procedure has to be in the same schema as the database schema object and it has to accept the following parameters: `(IN user_id BINARY(16), IN schema VARCHAR(255), IN object VARCHAR(255), IN crud_operation VARCHAR(4))`. It needs to returns `true` or `false`.

restViewAuthenticationProcedure ::=

### 2.5.8 Defining the GraphQL definition for a REST View

    graphQlObj:
        OPEN_CURLY graphQlPair (COMMA graphQlPair)* CLOSE_CURLY
        | OPEN_CURLY CLOSE_CURLY
    ;

    graphQlCrudOptions: (
            AT_INSERT
            | AT_NOINSERT
            | AT_UPDATE
            | AT_NOUPDATE
            | AT_DELETE
            | AT_NODELETE
            | AT_CHECK
            | AT_NOCHECK
        )+
    ;

    graphQlPair:
        graphQlPairKey COLON graphQlPairValue (
            AT_IN
            | AT_OUT
            | AT_INOUT
        )? graphQlValueOptions? (
            AT_DATATYPE OPEN_PAR graphQlDatatypeValue CLOSE_PAR
        )? graphQlCrudOptions? graphQlValueJsonSchema? graphQlObj?
    ;

    graphQlValueOptions: (
            AT_NOCHECK
            | AT_SORTABLE
            | AT_NOFILTERING
            | AT_ROWOWNERSHIP
            | AT_UNNEST
            | AT_KEY
        )+
    ;

    graphQlValue:
        qualifiedIdentifier
        | graphQlObj
    ;

    graphQlValueJsonSchema:
        JSON SCHEMA jsonValue
    ;

graphQlObj ::=

graphQlCrudOptions ::=

graphQlPair ::=

graphQlValue ::=

graphQlValueJsonSchema ::=

### 2.5.9 REST View Metadata

The metadata can hold any JSON data. It can later be consumed by a front end implementation to dynamically render certain attributes, like a specific icon or a color.

    metadata:
        METADATA jsonValue
    ;

### 2.5.10 Json Options for Views

The jsonOptions allow to set a number of specific options for the REST view. Specify the `MERGE` keyword to merge the given options with the existing options. If `MERGE` is omitted, all existing options will be overwritten with the specified options.

    jsonOptions:
        MERGE? OPTIONS jsonValue
    ;

    The following additional options can be configured for most database object endpoints in a JSON object through the OPTIONS clause (indentation means JSON object nesting):

    - `http`
      - see [REST Service JSON Options](#rest-service-json-options)
    - `logging`
      - see [REST Service JSON Options](#rest-service-json-options)
    - `metadata`
      - `gtid` (_bool_)
        - if true, embeds the GTID assigned to DB change operations into the metadata of the response JSON object.  Enable when using with replication topologies, to ensure that changes made to an object will be reflected when reading it,regardless of where the read happens. Default true.
    - `sqlQuery`
      - `embedWait` (_bool_)
        - if true, performs the wait described in the `wait` option directly in the DB query, as opposed to executing it beforehand in a separate statement.
      - `timeout` (_number_)
        - number of milliseconds to wait for the DB query to execute before it's terminated. Default is taken from the global `sqlQuery`.`timeout` option.
      - `wait` (_bool_)
        - when querying data from a secondary server, controls whether to wait until the transaction GTID specified through the `asof` clause are applied. Effectively enables read-own-writes semantics.
    - `result`
      - `cacheTimeToLive` (_double_)
        - enables caching for GET requests. Specifies the number of seconds (including sub-second values) to keep the response in the cache, after which it will be discarded until a new request comes in or when the cache fills up.
      - `includeLinks` (_bool_)
        - whether to include links in returned JSON objects (default true)
    - `returnInternalErrorDetails` (_bool_)
      - controls debug logging
    - `disableAutomaticGrants` (_bool_)
      - when creating or altering REST objects a list of privileges are automatically granted to the `mysql_rest_service_data_provider` role in order for the MySQL Router to be able to access the referenced data in the MySQL Server. In some cases it might be desirable to turn off this automatic grant of privileges and use the `grants` option to specify a custom list of grants.
    - `grants` (_object_ | _list_)
      - Either a single grant object or a list of grant objects that are executed in addition to the automatically generated grant statements for the REST object. These additional grants are needed when e.g. a stored PROCEDURE works with database TABLEs/VIEWs or calls other PROCEDUREs and FUNCTIONs.
      - `privileges` (_string_ | _list_)
        - Either a single privilege name or a list of privileges names or a list of privilege objects. The following MySQL privileges are allowed: "ALTER" | "ALTER ROUTINE" | "CREATE" | "CREATE ROUTINE" | "CREATE TEMPORARY TABLES" | "CREATE VIEW" | "DELETE" | "DROP" | "EVENT" | "EXECUTE" | "INDEX" | "INSERT" | "LOCK TABLES" | "REFERENCES" | "SELECT" | "SHOW DATABASES" | "SHOW VIEW" | "TRIGGER" | "UPDATE" | "USAGE". A privilege object has two fields, `privilege` and `columnList` with the latter holding a list of column names.
      - `objectType` (_string_)
        - Specifies an option object type, either "TABLE" | "FUNCTION" | "PROCEDURE".
      - `schema` (_string_)
        - The name of the database schema or `*`. The name needs to be provided without back ticks.
      - `object` (_string_)
        - The name of the database table/view/procedure/function or `*`. The name needs to be provided without back ticks.

    **Examples for `grants`:**

    The following example grants the SELECT privilege on the `mysql_rest_service_metadata`.`mrs_user` table.

    ```json
    {
        "grants": {
            "privileges": "SELECT",
            "schema": "mysql_rest_service_metadata",
            "object": "mrs_user"
        }
    }

This example grants the SELECT and UPDATE privileges on the `mysql_rest_service_metadata`.`mrs_user` table.

    {
        "grants": {
            "privileges": [ "SELECT", "UPDATE" ],
            "schema": "mysql_rest_service_metadata",
            "object": "mrs_user" }
    }

The following example grants two privileges.

    {
        "grants": [
            {
                "privileges": "SELECT",
                "schema": "mysql_rest_service_metadata",
                "object": "msm_schema_version"
            },
            {
                "privileges": "SELECT",
                "schema": "mysql_rest_service_metadata",
                "object": "mrs_user_schema_version"
            }
        ]
    }

This example grants the SELECT privilege only on the `id` and `name` columns of the `mysql_rest_service_metadata`.`mrs_user` table.

    {
        "grants": {
            "privileges": [
                {
                    "privilege": "SELECT",
                    "columnList": [
                        "id",
                        "name"
                    ]
                }
            ],
            "schema": "mysql_rest_service_metadata",
            "object": "mrs_user"
        }
    }

## 2.6 CREATE REST PROCEDURE

The `CREATE REST PROCEDURE` statement is used to add REST endpoints for database schema stored procedures. It uses the same extended GraphQL syntax as defined for REST data mapping views to describe the REST procedure’s parameters and result sets. Please make sure to study the corresponding section.

SYNTAX

    createRestProcedureStatement:    (
            CREATE OR REPLACE REST PROCEDURE
            | CREATE REST PROCEDURE (
                IF NOT EXISTS
            )?
        ) procedureRequestPath (ON serviceSchemaSelector)? AS qualifiedIdentifier
            FORCE? (
            PARAMETERS restObjectName? graphQlObj
        )? restProcedureResult* restObjectOptions?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

    restObjectOptions: (
            enabledDisabledPrivate
            | authenticationRequired
            | itemsPerPage
            | jsonOptions
            | comments
            | metadata
            | restViewMediaType
            | restViewFormat
            | restViewAuthenticationProcedure
        )+
    ;

    restProcedureResult:
        RESULT restResultName? graphQlObj
    ;

createRestProcedureStatement ::=

serviceSchemaSelector ::=

restObjectOptions ::=

restProcedureResult ::=

Examples

The following example adds a REST procedure for the `sakila.rewards_report` database schema procedure. It is assumed that a REST service `/myService` and a REST schema `/sakila` have already been created.

    CREATE OR REPLACE REST PROCEDURE /filmInStock
    ON SERVICE /myService SCHEMA /sakila
    AS sakila.rewards_report;

The following example adds a REST procedure for the `sakila.filmInStock` database schema procedure, while explicitly specifying the list of parameters and the RESULT returned by the procedure.

    CREATE OR REPLACE REST PROCEDURE /filmInStock
    ON SERVICE /myService SCHEMA /sakila
    AS sakila.film_in_stock
    PARAMETERS MyServiceSakilaFilmInStockParams {
        pFilmId: p_film_id @IN,
        pStoreId: p_store_id @IN,
        pFilmCount: p_film_count @OUT
    }
    RESULT MyServiceSakilaFilmInStock {
        inventoryId: inventory_id @DATATYPE("int")
    };

### 2.6.1 The FORCE Flag For Procedures

In certain cases, a REST procedure may need to be created even though the actual database schema procedure is not yet available. To make the `CREATE REST PROCEDURE` succeed in this case, the `FORCE` flag must be specified.

## 2.7 CREATE REST FUNCTION

The `CREATE REST FUNCTION` statement is used to add REST endpoints for database schema stored function. It uses the same extended GraphQL syntax as defined for REST data mapping views to describe the REST functions’s parameters and result. Please make sure to study the corresponding section.

SYNTAX

    createRestFunctionStatement:    (
            CREATE OR REPLACE REST FUNCTION
            | CREATE REST FUNCTION (
                IF NOT EXISTS
            )?
        ) functionRequestPath (ON serviceSchemaSelector)? AS qualifiedIdentifier
            FORCE? (
            PARAMETERS restObjectName? graphQlObj
        )? restFunctionResult? restObjectOptions?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

    restObjectOptions: (
            enabledDisabledPrivate
            | authenticationRequired
            | itemsPerPage
            | jsonOptions
            | comments
            | metadata
            | restViewMediaType
            | restViewFormat
            | restViewAuthenticationProcedure
        )+
    ;

    restFunctionResult:
        RESULT restResultName? graphQlObj
    ;

createRestFunctionStatement ::=

serviceSchemaSelector ::=

restObjectOptions ::=

restFunctionResult ::=

### 2.7.1 The FORCE Flag For Functions

In certain cases, a REST function may need to be created even though the actual database schema function is not yet available. To make the `CREATE REST FUNCTION` succeed in this case, the `FORCE` flag must be specified.

See JSON Options

## 2.8 CREATE REST CONTENT SET

The `CREATE REST CONTENT SET` statement is used to add REST endpoints for static content.

SYNTAX

    createRestContentSetStatement:    (
            CREATE OR REPLACE REST CONTENT SET
            | CREATE REST CONTENT SET (
                IF NOT EXISTS
            )?
        ) contentSetRequestPath (
            ON SERVICE? serviceRequestPath
        )? (FROM directoryFilePath)? restContentSetOptions?
    ;

    restContentSetOptions: (
            enabledDisabledPrivate
            | authenticationRequired
            | jsonOptions
            | comments
            | fileIgnoreList
            | loadScripts
        )+
    ;

createRestContentSetStatement ::=

restContentSetOptions ::=

## 2.9 CREATE REST CONTENT FILE

Adds a file to a content set.

SYNTAX

    createRestContentFileStatement:    (
            CREATE OR REPLACE REST CONTENT FILE
            | CREATE REST CONTENT FILE (
                IF NOT EXISTS
            )?
        ) contentFileRequestPath ON (
            SERVICE? serviceRequestPath
        )? CONTENT SET contentSetRequestPath (
            (FROM directoryFilePath)
            | (BINARY? CONTENT textStringLiteral)
        ) restContentFileOptions?
    ;

    restContentFileOptions: (
            enabledDisabledPrivate
            | authenticationRequired
            | jsonOptions
        )+
    ;

    directoryFilePath:
        textStringLiteral
    ;

createRestContentFileStatement ::=

restContentFileOptions ::=

## 2.10 CREATE REST AUTH APP

The `CREATE REST AUTH APP` statement is used to create a new REST authentication app. The MySQL REST Service supports a list of authentication vendors, including dedicated MRS authentication, MYSQL user account authentication as well as several OAuth2 vendors, like OCI OAuth2, Facebook and Google.

Once a REST authentication app has been created, it can be linked to REST services to enable the required authentication support.

The CREATE REST SERVICE and ALTER REST SERVICE statements support the addition or removal of REST authentication apps when using the ADD AUTH APP and REMOVE AUTH APP clauses

SYNTAX

    createRestAuthAppStatement:    (
            CREATE OR REPLACE REST (
                AUTH
                | AUTHENTICATION
            ) APP
            | CREATE REST (
                AUTH
                | AUTHENTICATION
            ) APP (IF NOT EXISTS)?
        ) authAppName VENDOR (
            MRS
            | MYSQL
            | vendorName
        ) restAuthAppOptions?
    ;

    restAuthAppOptions: (
            enabledDisabled
            | comments
            | allowNewUsersToRegister
            | defaultRole
            | appId
            | appSecret
            | url
        )+
    ;

    allowNewUsersToRegister:
        (DO NOT)? ALLOW NEW USERS (
            TO REGISTER
        )?
    ;

    defaultRole:
        DEFAULT ROLE textOrIdentifier
    ;

    appId:
        (APP | CLIENT) ID textStringLiteral
    ;

    appSecret:
        (APP | CLIENT) SECRET textStringLiteral
    ;

    url:
        URL textStringLiteral
    ;

    authAppName:
        textOrIdentifier
    ;

createRestAuthAppStatement ::=

restAuthAppOptions ::=

allowNewUsersToRegister ::=

defaultRole ::=

appId ::=

appSecret ::=

url ::=

Examples

The following example creates an REST authentication app using the MRS authentication vendor and links it to the REST service `/myService`.

    CREATE REST AUTHENTICATION APP "MRS" ON SERVICE /myService VENDOR MRS;

    ALTER REST SERVICE /myService ADD AUTH APP "MRS";

The next example creates an REST authentication app for the OCI OAuth2 service.

    CREATE REST AUTHENTICATION APP "OCI"
        VENDOR "OCI OAuth2"
        URL "https://idcs-f84866196ff54e3b93a15651865191da.identity.oraclecloud.com:443";
        CLIENT ID "f2abc2c0f19a4c40a1abc48edcdfe60b"
        CLIENT SECRET "**********************"

### 2.10.1 REST Authentication App Vendors

The following settings for `VENDOR` are currently supported.

REST Authentication App Vendors
Vendor | Type | Description
--- | --- | ---
`MRS` | MRS | Built in MRS authentication with dedicated MRS account management.
`MYSQL` | MySQL Server | MySQL server account authentication. This authentication method makes most sense for tooling and other applications with hardcoded accounts accessing the MySQL REST Service.
`Facebook` | OAuth2 | Performing authentication against the Facebook OAuth2 servers using `Login with Facebook`.
`Google` | OAuth2 | Performing authentication against the Google OAuth2 servers using `Login with Google`.
`"OCI OAuth2"` | OAuth2 | Performing authentication against the OCI OAuth2 service. See here for details on how to configure the OCI Auth2 service.

### 2.10.2 Configuring a REST Authentication App for OAuth2 access

Before creating a REST authentication app using an OAuth2 vendor, it is required to register the application at the OAuth2 vendor beforehand. Please consult the documentation of the individual vendors for more details.

For configuring the OCI OAuth2 service please see here.

Please note that the URL of the OAuth2 server is a required setting and must be specified.

During the registration process an APP ID (also called CLIENT ID) as well as an APP SECRET (also called CLIENT SECRET) will be generated by the OAuth2 vendor to uniquely identify the application. Both, the APP ID as well as the APP SECRET need to be specified when creating the REST authentication app.

In case of using OCI OAuth2 it is also required to specify the OCI “Domain URL” using the URL option.

## 2.11 CREATE REST USER

The `CREATE REST USER` statement is used to add REST user to a REST authentication app.

SYNTAX

    createRestUserStatement:    (
            CREATE OR REPLACE REST USER
            | CREATE REST USER (
                IF NOT EXISTS
            )?
        ) userName AT_SIGN authAppName (
            IDENTIFIED BY userPassword
        )? userOptions?
    ;

    userName:
        textOrIdentifier
    ;

    userPassword:
        textStringLiteral
    ;

    userOptions:
     (accountLock | appOptions | jsonOptions)+
    ;

    appOptions:
        APP OPTIONS jsonValue
    ;

    accountLock:
        ACCOUNT (LOCK | UNLOCK)
    ;

createRestUserStatement ::=

userOptions ::=

appOptions ::=

accountLock ::=

## 2.12 CREATE REST ROLE

Creates a REST role to the specified or currently active REST service. Role names must be unique across all services.

SYNTAX

    createRestRoleStatement:    (
            CREATE OR REPLACE REST ROLE
            | CREATE REST ROLE (
                IF NOT EXISTS
            )?
        ) roleName (EXTENDS parentRoleName)? roleService? restRoleOptions?
    ;

    restRoleOptions:
     (jsonOptions | comments)+
    ;

createRestRoleStatement ::=

restRoleOptions ::=

# 3 ALTER

## 3.1 ALTER REST SERVICE

An existing REST service can be altered by using the `ALTER REST SERVICE` statement. It uses the same `restServiceOptions` as used by the `CREATE REST SERVICE` statement. Please see the discussion of the options there.

SYNTAX

    alterRestServiceStatement:
        ALTER REST SERVICE serviceRequestPath (
            NEW REQUEST PATH newServiceRequestPath
        )? restServiceOptions?
    ;

    restServiceOptions: (
            enabledDisabled
            | publishedUnpublished
            | restProtocol
            | restAuthentication
            | jsonOptions
            | comments
            | metadata
            | addAuthApp
            | removeAuthApp
        )+
    ;

    addAuthApp:
        ADD AUTH APP authAppName (IF EXISTS)?
    ;

    removeAuthApp:
        REMOVE AUTH APP authAppName (IF EXISTS)?
    ;

alterRestServiceStatement ::=

restServiceOptions ::=

addAuthApp ::=

removeAuthApp ::=

Examples

The following example alters a REST service `/myService` by setting a new comment.

    ALTER REST SERVICE /myService
        COMMENT "A simple, improved REST service";

## 3.2 ALTER REST AUTH APP

Modifies attributes from an existing authentication app. See `CREATE REST AUTH APP` for details about supported options.

SYNTAX

    alterRestAuthAppStatement:
        ALTER REST (
            AUTH
            | AUTHENTICATION
        ) APP authAppName (
            NEW NAME newAuthAppName
        )? restAuthAppOptions?
    ;

alterRestAuthAppStatement ::=

## 3.3 ALTER REST SCHEMA

An existing REST schema can be altered by using the `ALTER REST SCHEMA` statement. It uses the same `restSchemaOptions` as used by the `CREATE REST SCHEMA` statement. Please see the discussion of the options there.

SYNTAX

    alterRestSchemaStatement:
        ALTER REST SCHEMA schemaRequestPath? (
            ON SERVICE? serviceRequestPath
        )? (
            NEW REQUEST PATH newSchemaRequestPath
        )? (FROM schemaName)? restSchemaOptions?
    ;

    restSchemaOptions: (
            enabledDisabledPrivate
            | authenticationRequired
            | itemsPerPage
            | jsonOptions
            | comments
            | metadata
        )+
    ;

alterRestSchemaStatement ::=

restSchemaOptions ::=

Examples

The following example alters a REST schema `/myService` to use a new request path `/myPublicService`.

    ALTER REST SCHEMA /sakila ON SERVICE /myService
        NEW REQUEST PATH /myPublicService;

## 3.4 ALTER REST VIEW

The `ALTER REST DATA MAPPING VIEW` statement is used to alter existing REST data mapping views.

Please see the corresponding GraphQL section about how to design the GraphQL definition for a REST data mapping view.

Please see the MRS Reference Manual to learn more about JSON data mapping views.

SYNTAX

    alterRestViewStatement:
        ALTER REST DATA? MAPPING? VIEW viewRequestPath (
            ON serviceSchemaSelector
        )? (NEW REQUEST PATH newViewRequestPath)? (
            CLASS restObjectName graphQlCrudOptions? graphQlObj?
        )? restObjectOptions?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

    restObjectOptions: (
            enabledDisabledPrivate
            | authenticationRequired
            | itemsPerPage
            | jsonOptions
            | comments
            | metadata
            | restViewMediaType
            | restViewFormat
            | restViewAuthenticationProcedure
        )+
    ;

alterRestViewStatement ::=

serviceSchemaSelector ::=

restObjectOptions ::=

Examples

The following example alters a REST data mapping view for the `sakila.city` database schema table and sets a new list of fields.

    ALTER REST VIEW /city
    ON SERVICE /myService SCHEMA /sakila
    FROM `sakila`.`city` AS MyServiceSakilaCity {
        cityId: city_id @SORTABLE,
        city: city
    };

## 3.5 ALTER REST PROCEDURE

The `ALTER REST PROCEDURE` statement is used to alter REST endpoints for database schema stored procedures.

It uses the same extended GraphQL syntax as defined for REST data mapping views to describe the REST procedure’s parameters and result sets. Please make sure to study the corresponding section.

SYNTAX

    alterRestProcedureStatement:
        ALTER REST PROCEDURE procedureRequestPath (
            ON serviceSchemaSelector
        )? (
            NEW REQUEST PATH newProcedureRequestPath
        )? (PARAMETERS restObjectName? graphQlObj)? restProcedureResult* restObjectOptions?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

    restObjectOptions: (
            enabledDisabledPrivate
            | authenticationRequired
            | itemsPerPage
            | jsonOptions
            | comments
            | metadata
            | restViewMediaType
            | restViewFormat
            | restViewAuthenticationProcedure
        )+
    ;

alterRestProcedureStatement ::=

serviceSchemaSelector ::=

restObjectOptions ::=

## 3.6 ALTER REST FUNCTION

The `ALTER REST FUNCTION` statement is used to alter REST endpoints for database schema stored functions.

It uses the same extended GraphQL syntax as defined for REST data mapping views to describe the REST procedure’s parameters and result sets. Please make sure to study the corresponding section.

SYNTAX

    alterRestFunctionStatement:
        ALTER REST FUNCTION functionRequestPath (
            ON serviceSchemaSelector
        )? (
            NEW REQUEST PATH newFunctionRequestPath
        )? (PARAMETERS restObjectName? graphQlObj)? restFunctionResult* restObjectOptions?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

    restObjectOptions: (
            enabledDisabledPrivate
            | authenticationRequired
            | itemsPerPage
            | jsonOptions
            | comments
            | metadata
            | restViewMediaType
            | restViewFormat
            | restViewAuthenticationProcedure
        )+
    ;

alterRestFunctionStatement ::=

serviceSchemaSelector ::=

restObjectOptions ::=

## 3.7 ALTER REST CONTENT SET

The `ALTER REST CONTENT SET` statement is used to alter REST content sets.

SYNTAX

    alterRestContentSetStatement:
        ALTER REST CONTENT SET contentSetRequestPath (
            ON SERVICE? serviceRequestPath
        )? (
            NEW REQUEST PATH newContentSetRequestPath
        )? restContentSetOptions?
    ;

    newContentSetRequestPath:
        requestPathIdentifier
    ;

alterRestContentSetStatement ::=

## 3.8 ALTER REST USER

Change password and options for an existing REST user account.

SYNTAX

    alterRestUserStatement:
        ALTER REST USER userName AT_SIGN authAppName (
            IDENTIFIED BY userPassword
        )? userOptions?
    ;

createRestUserStatement ::=

# 4 DROP

## 4.1 DROP REST SERVICE

An existing REST service can be dropped by using the `DROP REST SERVICE` statement.

SYNTAX

    dropRestServiceStatement:
        DROP REST SERVICE (
            IF EXISTS
        )? serviceRequestPath
    ;

dropRestServiceStatement ::=

Examples

The following example drops a REST service with the request path `/myService`.

    DROP REST SERVICE /myService;

## 4.2 DROP REST SCHEMA

An existing REST schema can be dropped by using the `DROP REST SCHEMA` statement.

SYNTAX

    dropRestSchemaStatement:
        DROP REST SCHEMA (
            IF EXISTS
        )? schemaRequestPath (
            FROM SERVICE? serviceRequestPath
        )?
    ;

dropRestSchemaStatement ::=

Examples

The following example drops a REST schema using the request path `/myService`.

    DROP REST SCHEMA /sakila FROM SERVICE /myService;

## 4.3 DROP REST VIEW

The `DROP REST DATA MAPPING VIEW` statement is used to drop existing REST data mapping views.

SYNTAX

    dropRestViewStatement:
        DROP REST DATA? MAPPING? VIEW (
            IF EXISTS
        )? viewRequestPath (FROM serviceSchemaSelector)?
    ;

dropRestViewStatement ::=

Examples

The following example drops a REST data mapping view using the request path `/city`.

    DROP REST VIEW /city
    FROM SERVICE /myService SCHEMA /sakila;

## 4.4 DROP REST PROCEDURE

The `DROP REST PROCEDURE` statement is used to drop an existing REST procedures.

SYNTAX

    dropRestProcedureStatement:
        DROP REST PROCEDURE (
            IF EXISTS
        )? procedureRequestPath (FROM serviceSchemaSelector)?
    ;

dropRestProcedureStatement ::=

## 4.5 DROP REST FUNCTION

The `DROP REST FUNCTION` statement is used to drop an existing REST functions.

SYNTAX

    dropRestFunctionStatement:
        DROP REST FUNCTION (
            IF EXISTS
        )? functionRequestPath (FROM serviceSchemaSelector)?
    ;

dropRestFunctionStatement ::=

## 4.6 DROP REST CONTENT SET

The `DROP REST CONTENT SET` statement is used to drop an existing REST static content set.

SYNTAX

    dropRestContentSetStatement:
        DROP REST CONTENT SET (
            IF EXISTS
        )? contentSetRequestPath (
            FROM SERVICE? serviceRequestPath
        )?
    ;

dropRestContentSetStatement ::=

## 4.7 DROP REST CONTENT FILE

Removes a file from a REST static content set.

SYNTAX

    dropRestContentFileStatement:
        DROP REST CONTENT FILE (
            IF EXISTS
        )? contentFileRequestPath FROM (
            SERVICE? serviceRequestPath
        )? CONTENT SET contentSetRequestPath
    ;

dropRestContentFileStatement ::=

## 4.8 DROP REST AUTH APP

The `DROP REST AUTH APP` statement is used to drop an existing REST authentication app from a REST service.

SYNTAX

    dropRestAuthAppStatement:
        DROP REST (AUTH | AUTHENTICATION) APP (
            IF EXISTS
        )? authAppName
    ;

dropRestAuthAppStatement ::=

## 4.9 DROP REST USER

The `DROP REST USER` statement is used to drop an existing REST user from a REST authentication app.

SYNTAX

    dropRestUserStatement:
        DROP REST USER (IF EXISTS)? userName AT_SIGN
            authAppName
    ;

dropRestUserStatement ::=

## 4.10 DROP REST ROLE

Drops the named REST role.

SYNTAX

    dropRestRoleStatement:
        DROP REST ROLE (IF EXISTS)? roleName roleService?
    ;

dropRestRoleStatement ::=

# 5 GRANT and REVOKE

## 5.1 GRANT REST

Grants REST privileges on endpoint objects to a role.

SYNTAX

    grantRestPrivilegeStatement:
        GRANT REST privilegeList (
            (ON SERVICE? serviceRequestPathWildcard)
            | (
                ON serviceSchemaSelectorWildcard (
                    OBJECT objectRequestPathWildcard
                )?
            )
        )? TO roleName roleService?
    ;

    privilegeList:
        privilegeName
        | privilegeName COMMA privilegeList
    ;

    privilegeName:
        CREATE
        | READ
        | UPDATE
        | DELETE
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

grantRestPrivilegeStatement ::=

privilegeList ::=

privilegeName ::=

## 5.2 GRANT REST ROLE

Grants a REST role to a user account.

SYNTAX

    grantRestRoleStatement:
        GRANT REST ROLE roleName roleService? TO userName AT_SIGN
            authAppName comments?
    ;

grantRestRoleStatement ::=

## 5.3 REVOKE REST

Revokes privileges on an REST endpoint object from a role.

SYNTAX

    revokeRestPrivilegeStatement:
        REVOKE REST privilegeList (
            (ON SERVICE? serviceRequestPathWildcard)
            | (
                ON serviceSchemaSelectorWildcard (
                    OBJECT objectRequestPathWildcard
                )?
            )
        )? FROM roleName roleService?
    ;

revokeRestPrivilegeStatement ::=

## 5.4 REVOKE REST ROLE

Revokes a role from a REST user.

SYNTAX

    revokeRestRoleStatement:
        REVOKE REST ROLE roleName roleService? FROM userName AT_SIGN
            authAppName
    ;

revokeRestRoleStatement ::=

# 6 USE and SHOW

## 6.1 USE

An existing REST service can be dropped by using the `DROP REST SERVICE` statement.

SYNTAX

    useStatement:
        USE REST serviceAndSchemaRequestPaths
    ;

    serviceAndSchemaRequestPaths:
        SERVICE serviceRequestPath
        | serviceSchemaSelector
    ;

useStatement ::=

serviceAndSchemaRequestPaths ::=

Examples

The following example makes the REST service with the request path `/myService` the new default REST service.

    USE REST SERVICE /myService;

After the default REST service has been set, the following statement can be used to set the default REST schema.

    USE REST SCHEMA /sakila;

The next example shows how to set the default REST service and REST schema in a single statement.

    USE REST SERVICE /myService SCHEMA /sakila;

## 6.2 SHOW REST STATUS

The `SHOW REST STATUS` statement is used to get basic information about the current status of the MySQL REST Service.

SYNTAX

    showRestMetadataStatusStatement:
        SHOW REST METADATA? STATUS
    ;

showRestMetadataStatusStatement ::=

Examples

The following example drops a REST schema using the request path `/myService`.

    SHOW REST STATUS;

## 6.3 SHOW REST SERVICES

The `SHOW REST SERVICES` statement lists all available REST services.

SYNTAX

    showRestServicesStatement:
        SHOW REST SERVICES
    ;

showRestServicesStatement ::=

Examples

The following example lists all REST services.

    SHOW REST SERVICES;

## 6.4 SHOW REST SCHEMAS

The `SHOW REST SCHEMAS` statement lists all available REST schemas of the given or current REST service.

SYNTAX

    showRestSchemasStatement:
        SHOW REST SCHEMAS (
            (ON | FROM) SERVICE? serviceRequestPath
        )?
    ;

showRestSchemasStatement ::=

Examples

The following example lists all REST schemas of the REST service using the request path `/myService`.

    SHOW REST SERVICES FROM /myService;

## 6.5 SHOW REST VIEWS

The `SHOW REST DATA MAPPING VIEWS` statement lists all available REST data mapping views of the given or current REST schema.

SYNTAX

    showRestViewsStatement:
        SHOW REST DATA? MAPPING? VIEWS (
            (ON | FROM) serviceSchemaSelector
        )?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

showRestViewsStatement ::=

serviceSchemaSelector ::=

Examples

The following example lists all REST data mapping views of the given REST schema.

    SHOW REST VIEWS FROM SERVICE /myService SCHEMA /sakila;

## 6.6 SHOW REST PROCEDURES

The `SHOW REST PROCEDURES` statement lists all available REST procedures of the given or current REST schema.

SYNTAX

    showRestProceduresStatement:
        SHOW REST PROCEDURES (
            (ON | FROM) serviceSchemaSelector
        )?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

showRestProceduresStatement ::=

serviceSchemaSelector ::=

## 6.7 SHOW REST FUNCTIONS

The `SHOW REST FUNCTIONS` statement lists all available REST functions of the given or current REST schema.

SYNTAX

    showRestFunctionsStatement:
        SHOW REST FUNCTIONS (
            (ON | FROM) serviceSchemaSelector
        )?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

showRestFunctionsStatement ::=

serviceSchemaSelector ::=

Examples

The following example lists all REST procedures of the given REST schema.

    SHOW REST PROCEDURES FROM SERVICE /myService SCHEMA /sakila;

## 6.8 SHOW REST CONTENT SETS

The `SHOW REST CONTENT SETS` statement lists all available REST content sets of the given or current REST service.

SYNTAX

    showRestContentSetsStatement:
        SHOW REST CONTENT SETS (
            (ON | FROM) SERVICE? serviceRequestPath
        )?
    ;

showRestContentSetsStatement ::=

Examples

The following example lists all REST content sets of the given REST service.

    SHOW REST CONTENT SETS FROM SERVICE /myService;

## 6.9 SHOW REST CONTENT FILES

The `SHOW REST CONTENT SETS` statement lists all available REST content files of the given content set.

SYNTAX

    showRestContentFilesStatement:
        SHOW REST CONTENT FILES (
            ON
            | FROM
        ) (SERVICE? serviceRequestPath)? CONTENT SET contentSetRequestPath
    ;

showRestContentFilesStatement ::=

## 6.10 SHOW CREATE REST CONTENT SET

Shows the CREATE SQL statement corresponding to the given content set.

SYNTAX

    showCreateRestContentSetStatement:
        SHOW CREATE REST CONTENT SET contentSetRequestPath (
            (ON | FROM) SERVICE? serviceRequestPath
        )?
    ;

showCreateRestContentSetStatement ::=

## 6.11 SHOW CREATE REST CONTENT FILE

Shows the CREATE SQL statement corresponding to the given content file.

SYNTAX

    showCreateRestContentFileStatement:
        SHOW CREATE REST CONTENT FILE contentFileRequestPath (
            ON
            | FROM
        ) (SERVICE? serviceRequestPath)? CONTENT SET contentSetRequestPath
    ;

showCreateRestContentFileStatement ::=

## 6.12 SHOW REST AUTH APPS

The `SHOW REST AUTH APPS` statement lists all available REST auth apps of the given or current REST service.

SYNTAX

    showRestAuthAppsStatement:
        SHOW REST AUTH APPS (
            (ON | FROM) SERVICE? serviceRequestPath
        )?
    ;

showRestAuthAppsStatement ::=

Examples

The following example lists all REST auth apps of the given REST service.

    SHOW REST AUTH APPS FROM SERVICE /myService;

## 6.13 SHOW CREATE REST SERVICE

The `SHOW CREATE REST SERVICE` statement shows the corresponding DDL statement for the given REST service.

SYNTAX

    showCreateRestServiceStatement:
        SHOW CREATE REST SERVICE serviceRequestPath? (
            INCLUDING SCHEMA ENDPOINTS
        )?
    ;

showCreateRestServiceStatement ::=

Examples

The following example shows the DDL statement for the REST service with request path `/myService`.

    SHOW CREATE REST SERVICE /myService;

## 6.14 SHOW CREATE REST SCHEMA

The `SHOW CREATE REST SCHEMA` statement shows the corresponding DDL statement for the given REST schema.

SYNTAX

    showCreateRestSchemaStatement:
        SHOW CREATE REST SCHEMA schemaRequestPath? (
            (ON | FROM) SERVICE? serviceRequestPath
        )?
    ;

showCreateRestSchemaStatement ::=

Examples

The following example shows the DDL statement for the given REST schema.

    SHOW CREATE REST SCHEMA /sakila FROM /myService;

## 6.15 SHOW CREATE REST VIEW

The `SHOW CREATE REST DATA MAPPING VIEW` statement shows the corresponding DDL statement for the given REST data mapping view.

SYNTAX

    showCreateRestViewStatement:
        SHOW CREATE REST DATA? MAPPING? VIEW viewRequestPath (
            (ON | FROM) serviceSchemaSelector
        )?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

showCreateRestViewStatement ::=

serviceSchemaSelector ::=

Examples

The following example shows the DDL statement for the given REST data mapping view.

    SHOW CREATE REST VIEW /city ON SERVICE /myService SCHEMA /sakila;

## 6.16 SHOW CREATE REST PROCEDURE

The `SHOW CREATE REST PROCEDURE` statement shows the corresponding DDL statement for the given REST procedure.

SYNTAX

    showCreateRestProcedureStatement:
        SHOW CREATE REST PROCEDURE procedureRequestPath (
            (ON | FROM) serviceSchemaSelector
        )?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

showCreateRestProcedureStatement ::=

serviceSchemaSelector ::=

## 6.17 SHOW CREATE REST FUNCTION

The `SHOW CREATE REST FUNCTION` statement shows the corresponding DDL statement for the given REST function.

SYNTAX

    showCreateRestFunctionStatement:
        SHOW CREATE REST FUNCTION functionRequestPath (
            (ON | FROM) serviceSchemaSelector
        )?
    ;

    serviceSchemaSelector:
        (SERVICE serviceRequestPath)? SCHEMA schemaRequestPath
    ;

showCreateRestFunctionStatement ::=

serviceSchemaSelector ::=

Examples

The following example shows the DDL statement for the given REST procedure.

    SHOW CREATE REST PROCEDURE /inventory_in_stock ON SERVICE /myService SCHEMA /sakila;

## 6.18 SHOW CREATE REST AUTH APP

The `SHOW CREATE REST AUTH APP` statement shows the corresponding DDL statement for the given REST auth app.

SYNTAX

    showCreateRestAuthAppStatement:
        SHOW CREATE REST AUTH APP authAppName
    ;

showCreateRestAuthAppStatement ::=

Examples

The following example shows the DDL statement for the given REST auth app.

    SHOW CREATE REST AUTH APP "MRS" FROM SERVICE /myTestService;

## 6.19 SHOW CREATE REST ROLE

The `SHOW CREATE REST ROLE` statement shows the corresponding DDL statement for the given REST role.

SYNTAX

    showCreateRestRoleStatement:
        SHOW CREATE REST ROLE roleName roleService?
    ;

    roleService:
        ON (
            ANY SERVICE
            | SERVICE? serviceRequestPath
        )
    ;

showCreateRestRoleStatement ::=

roleService ::=

Examples

The following example shows the DDL statement for the given REST auth app.

    SHOW CREATE REST ROLE `myrole` ON SERVICE /myTestService;

## 6.20 SHOW CREATE REST USER

The `SHOW CREATE REST USER` statement shows the corresponding DDL statement for the given REST user account.

SYNTAX

    showCreateRestUserStatement:
        SHOW CREATE REST USER userName AT_SIGN authAppName
    ;

showCreateRestUserStatement ::=

Examples

The following example shows the DDL statement for the given REST auth app.

    SHOW CREATE REST USER myuser@`MRS` ON SERVICE /myTestService;

## 6.21 SHOW REST ROLES

Shows a list of roles, optionally filtered by service or auth app and users that were granted the role.

SYNTAX

    showRestRolesStatement:
        SHOW REST ROLES (
            (ON | FROM) (
                ANY SERVICE
                | SERVICE? serviceRequestPath
            )
        )? (FOR userName? AT_SIGN authAppName)?
    ;

showRestRolesStatement ::=

## 6.22 SHOW REST GRANTS

Show the list of REST privileges that were granted to the given role.

SYNTAX

    showRestGrantsStatement:
        SHOW REST GRANTS FOR roleName (
            (ON | FROM) (
                ANY SERVICE
                | SERVICE? serviceRequestPath
            )
        )?
    ;

showRestGrantsStatement ::=

# 7 DUMP

## 7.1 DUMP REST PROJECT

An existing REST service can be dumped as REST project by using the `DUMP REST PROJECT` statement.

The command will generate a directory containing the following:

- `mrs.package.json` containing the project details
- `*.service.mrs.sql` containing the REST SQL for each service
- other SQL files containing schema dumps
- directories containing schema dumps
- `appIcon.*` being the icon for this project

This directory may then be zipped into a file.

SYNTAX

    dumpRestProjectStatement:
        DUMP REST PROJECT
        restProjectName VERSION restProjectVersion
        (dumpRestProjectService)+
        (dumpRestProjectDatabaseSchema)*
        (dumpRestProjectSettings)?
        TO (ZIP)? directoryFilePath
    ;

    dumpRestProjectService:
        SERVICE serviceRequestPath
            INCLUDING ((DATABASE (AND STATIC (AND DYNAMIC)?)?) | ALL) ENDPOINTS
    ;

    dumpRestProjectDatabaseSchema:
        DATABASE schemaName (FROM restProjectDatabaseSchemaFilePath)?
    ;

    dumpRestProjectSettings: (
            ICON FROM restProjectIconFilePath
            | DESCRIPTION restProjectDescription
            | PUBLISHER restProjectPublisher
        )+
    ;

dumpRestProjectStatement ::=

dumpRestProjectService ::=

dumpRestProjectDatabaseSchema ::=

dumpRestProjectSettings ::=

Examples

The following example dumps the REST service with the request path `/myService` to a REST project, including the database schema `sakila` it is based on.

    DUMP REST PROJECT 'myServiceProject' VERSION '1.0.0'
        SERVICE /myService INCLUDING ALL ENDPOINTS
        DATABASE `sakila`
        DESCRIPTION 'My first REST project'
        PUBLISHER 'Oracle'
        TO ZIP '~/myServiceProject.zip';

Here’s a full example to dump a REST service containing most variations of the command.

    DUMP REST PROJECT 'myProject' VERSION '1.0.0'
        SERVICE /myService INCLUDING DATABASE AND STATIC AND DYNAMIC ENDPOINTS
        SERVICE /myService2 INCLUDING ALL ENDPOINTS
        DATABASE `chatApp` FROM '~/mrs_plugin/examples/mrs_chat/db_schema/chat_db_schema.sql'
        DATABASE `chatRestService` FROM '~/mrs_plugin/examples/mrs_chat/db_schema/chat_rest_service.sql'
        DATABASE `chatApp2` FROM '~/mrs_plugin/examples/mrs_chat/db_schema/'
        DATABASE `sakila`
        DESCRIPTION 'This is my first project'
        PUBLISHER 'Oracle'
        ICON FROM '~/icon.svg'
        TO ZIP '~/project.myService.zip';

Lets go through the command an explain it in detail.

The first part `DUMP REST PROJECT 'myProject' VERSION '1.0.0'` is the project name and version. The version is not strict to any version format, allowing for `'v1.0'` or `'1.0.0b'` to be valid versions.

Following we have the services that should be included in the project. You can check the

    SERVICE /myService INCLUDING DATABASE AND STATIC AND DYNAMIC ENDPOINTS

The service request path is referring to the service required on the project and you are able to include multiple services in the project. Each of these statements will create its own REST SQL file containing all the REST SQL commands to recreate the service. From that service, you choose what to include: - `DATABASE` include REST objects like TABLE, VIEW, PROCEDURE, FUNCTION and SCRIPT - `STATIC` include content sets that are not of SCRIPT type - `DYNAMIC` include content sets that are of SCRIPT type - `ALL` short for `DATABASE AND STATIC AND DYNAMIC`

Each of these settings are a superset of the former.

Then we have the `DATABASE` sub-statements that either dump a schema

    DATABASE `sakila`

or uses a SQL file containing the dump of a schema

    DATABASE `chatApp` FROM '~/mrs_plugin/examples/mrs_chat/db_schema/chat_db_schema.sql'

Then we can find the project settings. These settings are optional but brings some detail to the project.

- `DESCRIPTION` is a short description for the project.
- `PUBLISHER` the owner or publisher of the project.
- `ICON` will copy an icon file from the specified path.

All this information will be in the `mrs.package.json` project file.

Finally there’s the `TO ZIP '~/project.myService.zip'` which defined the output of the command. The command can generate a directory with all the contents or, if the `ZIP` command is used, generate a zip file with the directory contents.

## 7.2 DUMP REST SERVICE

An existing REST service can be dumped to disk by using the `DUMP REST SERVICE` statement. This dump does not include the database schema that it is based on. To create a fully consistent dump that also includes the database schema, please use the `DUMP REST PROJECT` statement instead.

    dumpRestServiceStatement:
        DUMP REST SERVICE serviceRequestPath AS (
            SQL
        )? SCRIPT INCLUDING (
            (
                DATABASE (
                    AND STATIC (
                        AND DYNAMIC
                    )?
                )?
            )
            | ALL
        ) ENDPOINTS TO (ZIP)? directoryFilePath
    ;

dumpRestServiceStatement ::=

Examples

The following example dumps the REST service with the request path `/myService`.

    DUMP REST SERVICE /myService AS SQL SCRIPT INCLUDING DATABASE AND STATIC AND DYNAMIC ENDPOINTS TO '~/myService.sql'

    DUMP REST SERVICE /myService AS SQL SCRIPT INCLUDING ALL ENDPOINTS TO ZIP '~/myService.zip';

The service request path is referring to the service required on the project and you are able to include multiple services in the project. This statements will create a REST SQL file containing all the REST SQL commands to recreate the service. From that service, you choose what to include: - `DATABASE` include REST objects like TABLE, VIEW, PROCEDURE, FUNCTION and SCRIPT - `STATIC` include content sets that are not of SCRIPT type - `DYNAMIC` include content sets that are of SCRIPT type - `ALL` short for `DATABASE AND STATIC AND DYNAMIC`

Each of these settings are a superset of the former.

The destination file is defined with the `TO` or `TO ZIP` expression when the created file is a REST SQL script or a zipped REST SQL file.

Copyright (c) 2023, 2025, Oracle and/or its affiliates.