Endpoint Protocol

This section describes the protocol used to call API endpoints.

Executing endpoints

Consider the following endpoint declaration and code files:

/endpoint.yml

raw: "0.10"
endpoint: GET
metadata:
  title: Simple Get
  description: Hello World get!
code: snapi
codeFile: code.snapi
format: json
computeClass: normal
computeLimitSeconds: 30

/code.snapi

main() = [
 {a: 1, b: "Hello"}
 {a: 2, b: "World"},
 {a: 3, b: "Again!"}
]

Once this endpoint is published, RAW will expose it as a REST endpoint which can be accessed with an HTTP GET request. The cURL command illustrates how to execute this endpoint:

$ curl https://acme.raw-labs.com/main/endpoint \
   -H "Accept: application/json" \
   -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

[{"a":1,"b":"Hello"},{"a":2,"b":"World"},{"a":3,"b":"Again!"}]

Execution model

The time to execute of an endpoint can vary depending on the complexity of the query, caching as well as other factors.

To avoid overloading the system, RAW will only run a single execution of an endpoint for a given parameter set at a time.

When a request arrives, if there is no ongoing execution for this endpoint and parameter set, and the results are not cached, RAW will start a new execution. However, if there is an ongoing execution, it will wait for the current execution to finish and return the results of that execution.

This has several implications:

• Clients can make several requests to the same endpoint without worrying about overloading the system. If RAW receives 10 simultaneous requests for the same endpoint, there will be a single execution at any point in time.
• Clients may see slightly out-of-date results. Let's say there is a query that started at 10h and takes 10 minutes to run. If another client sends a request at 10:09, it will receive the results returned by this ongoing query. If the data sources used by the endpoint have changed after 10h, the query that was started at 10h might have seen the previous state of the data sources, so the results returned to the request sent at 10:09 might not reflect the latest state of the data. This will happen even if caching of results is disabled.

Long-running executions

To avoid keeping an HTTP request open for long time, RAW will respond with 202 Accepted after a certain timeout has elapsed.

The default timeout is 30 seconds but each RAW deployment can have its own timeout.

When receiving a 202 response, the client should retry the request, until it receives the results of executing the endpoint in a 200 OK response.

The following cURL commands illustrate this situation:

$ curl -v https://acme.raw-labs.com/main/endpoint \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN"
> GET /main/endpoint HTTP/1.1
> Authorization: Bearer ACCESS_TOKEN
...
[ Long delay ]
< HTTP/1.1 202 Accepted
...
Results are not yet ready, please try again later. If using a browser, refresh in a few seconds.

The client continues retrying until getting a 200 OK response:

$ curl -v https://acme.raw-labs.com/main/endpoint \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN"
> GET /main/endpoint HTTP/1.1
> Authorization: Bearer ACCESS_TOKEN
...
< HTTP/1.1 200 OK
[{"a":1,"b":"Hello"},{"a":2,"b":"World"},{"a":3,"b":"Again!"}]

HTTP responses

The following are the list of HTTP responses:

HTTP Status	Description	Content Type
200	Endpoint executed correctly. The results are returned.	application/json
202	Endpoint execution is ongoing. Retry in few moments.	text/plain
400	Endpoint execution failed. The error response is returned.	application/json
401	Endpoint not authorized for the given access token.	none
403	User not allowed to access this endpoint.	none
404	Endpoint not found.	none
405	Method not allowed. POST endpoints are not yet supported.	none

The 400 error responses contain a JSON object describing the error with the following format:

{
    "code": "",
    "message": ""
}

The code can be one of:

• validationError - The query failed to validate.
• runtimeError - The execution failed at runtime.
• executionComputeLimitExceeded - The execution reached the compute time limit and was aborted.
• argumentsError - Invalid argument provided to the endpoint.
• endpointNotFound - Endpoint does not exist.
• invalidEndpoint - Endpoint is not enabled.
• genericError - An error that does not fit in any of the categories above.

Validation error response

If the query failed to validate, the response will have additional fields describing the validation errors.

{
    "code": "validationError",
    "message": "",
    "validationErrors": [
        {
            "message": "",
            "positions": [
                {
                    "begin": {
                        "line": 3,
                        "column": 2
                    },
                    "end": {
                        "line": 3,
                        "column": 6
                    }
                }
            ]
        }
    ]
}

Runtime error response

If the query fails during execution, the response will have an additional field runtimeError:

{
    "code": "runtimeError",
    "message": "",
    "runtimeError": ""
}

Executing secured endpoints

Endpoint security is defined via the security option in the configuration file,