API

The core of rngo is its API, which is available at https://api.rngo.dev.

Authentication

All requests to the API must be authenticated with an API key, which can be created at rngo.dev/api-keys.

The API key must be sent in theAuthorization header, with the standard "Bearer " prefix, e.g.:

curl -X POST https://api.rngo.dev/simulations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rngo_duwCbxeFXbjFghKKJuwrbkzWzTLQpOol" \
  -d '{
    "seed": 7,
    "streams": {
      "users": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" }
        }
      }
    }
  }'

Errors

When something goes wrong, the API will respond with any of the following HTTP codes, depending on the nature of the problem:

401 Unauthorized

TheAuthorization header is not set, is malformed, or the API key is invalid.

404 Not Found

The resource referenced by the URL does not exist.

422 Unprocessible Entity

The request body is well-formed JSON, but contains validation errors.

500 Internal Server Error

There was an unhandled issue in the API.

Most error responses have a JSON body, and when they do theContent-Type header will be set to application/problem+json.

The simplest problem is just a title:

{
  "title": "Auth error"
}

Problems can also have one or more issues:

{
  "title": "Invalid request body",
  "issues": [
    {
      "message": "Must specify one of 'foo' or 'bar'"
    },
    {
      "path": ["posts", 3, "id"],
      "message": "Unknown ID",
    }
  ]
}

An issue must have amessage. If one has a path, it points to a value in the request body.