Using the API Catalog in RAW

The Catalog contains all published endpoints and their information. The catalog is accessed via the Catalog icon on the side bar. The respective screen is the following:

A list of endpoints in a tree format can be seen on the left panel. Upon selection of an endpoint the respective information appears on the right panel.

In that panel on the right, there are three tabs available:

• Description: provides the details of the endpoint.
• Deployment Settings: provides the hardware details of the endpoint
• Activity: provides the activity of the endpoint

Endpoint Description

All business-related information about a selected endpoint is shown in the Endpoint Description panel, as the following image shows:

All fields are analyzed below.

Title and description

The title and the description of the endpoint. These attributes are defined for informative purposes about the type and general functionality of this endpoint. Endpoint creators are free to specify arbitrary information within these attributes.

Invocation Details

The invocation details include the following attributes:

• Path, which is the URL of this endpoint
• Type of invocation endpoint, e.g. GET or POST

An endpoint may or may not receive input arguments. This is automatically deduced upon processing of the underlying Snapi code. Here is an example of an parameterized endpoint:

The invocation details provide the invocation URL and the type of invocation endpoint.

Data Details

Data details relate to the output payload of the selected endpoint. Two attributes are specified:

• Output Format: the format of the data returned by the endpoint;
• Output Type: the type of the data returned by the endpoint.

Security

The endpoints can be Public or Private. Public endpoints are openly accessible by any user without prior authentication/authorization. Private endpoints are restricted to be accessbile by users with specific scopes. A scope is a list of tags (plain strings)

Here is an example of a public endpoint:

Here is an example of a private endpoint with a specific scope, called iss:

Deployment Settings

The deployment settings of the endpoint. The hardware preferences used for this specific endpoint

Resources

• Class: The computation class is deferred for free and enterprise users. Different amount of compute power is spent on different types of installation
• Cache size: The cache size for endpoint invocations in MBs
• Compute Limit: Number of seconds threshold before compute task is interrupted

Refresh Every

Cache time-to-live in seconds before refresh.

Format

Endpoint output format. Available values are json and csv.

Activity

This tab visualizes the activity of the selected endpoint. The term activity refers to the invocations of the endpoint made by a user or a computer program. These are logged and shown to the user in reverse chronological order:

There are several elements shown in this screen:

• ID: an identifier for the specified invocation attempt
• Date: invocation timestamp
• State: an indication of success (SUCCESS) or failure (FAILED) of the invocation.
• Invocation Details (View): contextual information of the invocation including execution environment attributes and error messages

Invocation Details

As stated previously, there are two types of contextual information regarding an endpoint invocation, namely info and messages.

Info

Clicking on Info button users can see the execution environment attributes of the selected invocation attempt:

These attributes are the following:

• Settings: environment settings defined in the endpoint yaml. Specifically:
  • Compute Cache Size Mb: cache size in megabytes.
  • Compute Class: computational class to use.
  • Compute Limit Seconds: number of seconds threshold before compute task is interrupted.
  • Format: endpoint output format. Potential values: json, csv.
  • Refresh Period Seconds: cache time-to-live in seconds before refresh.
• Parameters: list of pairs of input parameter and respective value, defined by the called.
• Stats
  • Cached: true if the invocation is cached or false otherwise.
  • Credits Consumed: number of credits consumed during invocation. Currently credits are set to 0.
  • Execution Time: number of milliseconds of the actual execution, without considering network delay.
  • Output Size: volume of output data in KBs.

Messages

In case of errors, additional information is exposed by clicking on Messages button:

One invocation may result in multiple errors, each shown in distinct line. Each record has the following attributes:

• Date: timestamp of the error
• Level: ERROR or WARNING. An error is a terminal event which causes invocation failure, whereas a warning may not result in invocation failure.
• Message: the actual error/warning explanation

Indicatively, in the specific error shown above, users are informed of the fact that the endpoint should receive certain input arguments but none was provided.

Note also that upon successfull invocation, this functionality is not applicable, therefore the Messages button is disabled.