Application Protocol Interface (API)

The Scramjet Cloud Platform API enables programmatic access to SCP in a unique and advanced ways. With this ability a user can get, post, put, and delete a Sequence. SCP supports cURL command-line transfer library to transfer data to and from SCP and in addition to that Scramjet Cloud Platform (SCP) adheres to the Representational state transfer (REST) API protocol and architecture which includes following methods:

Methods

  1. [ GET ] - All operations requesting data from the Scramjet Cloud Platform (SCP).
  2. [ POST ] - Creating a new Hub, Sequence, or for messaging and streaming data to a Sequence.
  3. [ PUT ] - Updating existing Sequences or Instances,
  4. [ DELETE ] - Removing operations on a Hub or a Space.

Authorization


In order for a user to access Scramjet Cloud platform through Rest API using the cURL command-line, the following basic procedure must be included. A user must carry out the same procedure for the rest of cURL command-lines. Defining the request as follows:

Section Content
Base URL: https ://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1
Method: GET, POST, PUT, or DELETE
Headers: -H "accept: */*" -H "authorization: Bearer <Generated-Token>" -H "content-type: media-type"

Sequence Store operations

Store Base URL: https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1

[ GET ] {API Base}/s3 - list all Sequences

HTTP request

curl -v --location --request GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/s3" -H "Authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ PUT ] {API Base}/s3 - add a Sequences

HTTP request

curl -v --location --request PUT --upload-file "Path/to/filename.tar.gz" "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/s3" -H "accept: */*" -H "Authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Content-Type: application/octet-stream" -H "Transfer-Encoding: chunked"

[ DELETE ] {API Base}/s3/filename.tar.gz - delete a Sequences

HTTP request

curl -v --request DELETE "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/s3/<filename.tar.gz>" -H "Authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/s3/filename.tar.gz - download a Sequences

HTTP request

curl --location --request GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/s3/<filename.tar.gz>" -H "Authorization: Bearer <GENERATED-TOKEN>" --output "Path/to/downloads/<filename.tar.gz>"

NOTE: Sequences stored on the Sequence Store can be started through an assigned Space-id and Hub-id by including the <Sequence-id> of a Sequence listed undernear the Sequence store listings to the Sequence start API endpoint. The Sequences stored on the Sequence Store will remain available even if they were deleted from a Hub.


Space operations

Space Base URL: https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1

[ GET ] {API Base}/version - show space version

HTTP request

curl -v --location --request GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/version" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/load - show space load info

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/load" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/list - list space Hubs

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/list" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/sequences - show all Sequences on Space

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sequences" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"

[ GET ] {API Base}/instances - show list of Instances on Space

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/instances" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"

[ GET ] {API Base}/log - show logs form Space

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/log" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"

Responses

Content-type: application/octet-stream

[ GET ] {API Base}/sth/:id/info - show the Hub info

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/info" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"


Hub operations

Hub Base URL: https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1

[ GET ] {API Base}/version - show the Hub version

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/version" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/config - show the Hub config

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/config" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/load-check - monitor CPU, memory and disk usage metrics on the Hub machine

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/load-check" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/log - show logs form Hub

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/log" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/topics - list Space Topics

HTTP request

curl --location --request GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/topics" -H "accept: */*" -H "Authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"

[ POST ] {API Base}/topic/:name​ - sends data to the Topic, if it does not exist, the Topic is created

HTTP request

curl -v --location --data "<STRING>" "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/topic/<TOPIC-NAME>" -H "accept: */*" -H "Authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"

Request Headers

Content-type: application/x-ndjson

Responses

Status: 200 - Success - when data to topic is sent with the header indicating the end of data Status: 202 - accepted - when data to topic is sent without the header indicating the end of data (default)

[ GET ] {API Base}/topic/:name​ - get data from the Topic

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/topic/<TOPIC-NAME>" -H "accept: */*" -H "Authorization: Bearer <GENERATED-TOKEN>"


Sequence operations

Sequence Base URL: https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1

[ GET ] {API Base}/sequences - show all Sequences saved on the Hub

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequences" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/sequence/:id - show Sequence details

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequence/<SEQUENCE-ID>" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/sequence/:id/instances - show Instances of a Sequence

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequence/<SEQUENCE-ID>/instances" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ POST ] {API Base}/sequence - add new Sequence

Parameters

Name Description Type Required
file compressed package in tar.gz format binary yes
appConfig additional package.json config file json no
x-name alias name for sequence header no

HTTP request

curl -v --location --request POST --upload-file "PATH/TO/filename.tar.gz" "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequence" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Content-Type: application/octet-stream" -H "Transfer-Encoding: chunked"

[ PUT ] {API Base}/sequence/:id_name - update exising Sequence

Parameters

Name Description Type Required
file compressed package in tar.gz format binary yes
appConfig additional package.json config file json no
x-name alias name for sequence header no

[ POST ] {API Base}/sequence/:id/start - start chosen Sequence

Parameters

Name Description Type Required
appConfig additional package.json config file json no
args additional arguments that instance should starts with json no

HTTP request

curl -v --location --request POST "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequence/<SEQUENCE-ID>/start" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"

[ DELETE ] {API Base}/sequence/:id - delete a Sequence by Sequence-id Note: If an Instance is started from a given Sequence, the Sequence can not be removed.

HTTP request

curl -v --location --request DELETE "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequence/<SEQUENCE-ID>" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"


Instance operations

Instance Base URL: https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1

[ GET ] {API Base}/instances - show list of Instances running on the Hub

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instances" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/instance/:id - show data of a chosen Instance

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ POST ] {API Base}/instance/:id/_stop - end an Instance gracefully, prolongs an operation to be completed​

Parameters

Name Description Type Required
timeout The number of milliseconds before the Instance will be killed. Default: 7000ms. number no
canCallKeepalive If set to true, the instance will prolong the running. Default: false. boolean no

HTTP request

curl -v --location --request POST "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/_stop" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ POST ] {API Base}/instance/:id/_kill - end an Instance gracefully while waiting for an unfinished task

HTTP request

curl -v --location --request POST "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/_kill" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ GET ] {API Base}/instance/:id/health - check health status of an Instance

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/health" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"

[ POST ] {API Base}/instance/:id/input - send data to the Instance

HTTP request

  • Input data as a string

curl -v --data "<STRING>" POST "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/input" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Content-Type: text/plain"

  • Input data from a file

curl -v --request POST --upload-file "Path/to/file.txt" "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/input" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Content-Type: text/plain"

  • Input data through keyboard

curl -v -X POST --include "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/input" --header "Content-Type: text/plain" --header "Transfer-Encoding: chunked" -H "authorization: Bearer <GENERATED-TOKEN>" --no-buffer -T -

[ GET ] {API Base}/instance/:id/output - get the output stream from the Instance

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/output" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"

[ POST ] {API Base}/instance/:id/stdin​ - process.stdin

HTTP request

curl -v --request POST --upload-file "Path/to/file.txt" "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/stdin" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Transfer-Encoding: chunked" -H "content-type: application/octet-stream"

[ GET ] {API Base}/instance/:id/stdout - process.stdout

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/stdout" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "Transfer-Encoding: chunked" -H "content-type: application/octet-stream"

[ GET ] {API Base}/instance/:id/stderr - process.stderr

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/stderr" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Transfer-Encoding: chunked" -H "content-type: application/octet-stream"

[ GET ] {API Base}/instance/:id/log - stream all instance logs

HTTP request

curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/log" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>"

[ POST ] {API Base}/instance/:id/_event - send an Event to the Instance

Parameters

Name Type Description Required
eventName string Name of an event true
message string JSON formatted event payload false

HTTP request

curl --location --request POST "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/_event" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json" --data-raw "[5001,{\"eventName\": \"<NAMED-EVENT>\" ,\"message\": \"<SENT-MESSAGE>\"}]"

[ GET ] {API Base}/instance/:id/event - get the data stream with the Events from the Instance

HTTP request

curl --location --request GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/event/<EVENT-RESPONSE-NAME>" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/octet-stream"

[ GET ] {API Base}/instance/:id/once - get the last Event sent by the Instance

Headers

Content-type: application/octet-stream


The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by RFC7231 and registered status codes are listed in the IANA Status Code Registry.
The most common HTTP status codes handled by requested Scramjet endpoints are placed in the table below as part of the REST methods returning HTTP status codes, notifying the calling client of the failure or success of the REST request.

Status code Description
200 Success The request completed successfully.
202 Accepted The request has been accepted for processing, but the processing has not been completed.
204 No Content The request completed successfully, but content is not available.
400 Bad Request The REST request contains parameters that are not valid or missing.
401 Unauthorized The caller is not authorized to perform the request.
403 Forbidden The caller is not authorized to complete the request.
404 Not Found The requested resource does not exist.
406 Not Acceptable The request contains an unsupported content type or content encoding.
412 Invalid syntax The request uses an invalid regular expression in the fieldname parameter for collection types.
419 Insufficient Resources Insufficient RAM memory availability.
422 Unprocessable Entity Error encountered when unpacking a sequence.
500 Internal Server Error A problem has occurred. Additional information is provided in the stack trace.

Useful hints for Json processing while using cURL on the Terminal:

  • For Windows Terminal make sure to use double quotation when needed
  • For Pretty Print Json
    1. npm install -g jsontool
    2. use the pipe <| json> at the end of curl request on the terminal
    OR
    1. Download JQ
    2. Rename jq-win64.exe to jq.exe
    3. Place jq.exe in C:\Windows\System32
    4. use the pipe <| jq> at the end of curl request on the terminal

Was it helpful?

Didn't find information needed?

Join our Scramjet Community on Discord, where you can get help from our engineers directly.