Skip to main content

Testing with Sample responses

API Studio

Each API version has a Design preview URL. It answers requests from the version's saved document with Sample responses, so you can try an API before anything is built behind it. API Studio > Test > Try it sends requests to it with the Simulated target.

Testing needs the API test permission.

The Design preview URL​

The URL has this shape:

https://<your DataLug address>/t/<account short code>/preview/<api slug>/<version>/<operation path>

It uses the same address as the DataLug app. API Studio > Test > Try it and your own tools send requests to the same URL.

The Design preview URL never calls another system. Every answer comes from the saved document.

Create a test key​

Every request needs a test key for the API.

  1. Open the API and open API Studio > Test > Try it.
  2. Under Test keys, enter a Key name and press Create key.
  3. Copy the key. It is shown once.

The list shows each key by name and prefix. Press Revoke to stop a key working. A key opens only the API it was created for.

Each API has a limit on active test keys, set by your administrator. When the limit is reached, revoke a key before you create another.

Send the key in one of these headers:

  • Authorization: Bearer <key>
  • X-Api-Key: <key>

Send a request​

  1. In API Studio > Test > Try it, pick an Operation. In API Studio > Design > Endpoints, Try it on a row opens API Studio > Test > Try it with that operation.
  2. Leave Target on Simulated.
  3. Enter the key in Test key.
  4. Fill in the parameters and the body. Both start from the operation's schema.
  5. Press Send.

The answer shows the status, the headers, the body and any validation problems. Copy as curl copies the same request for a terminal, with the key written as $DATALUG_TEST_KEY.

How the answer is chosen​

A valid request gets the operation's success response, with its declared status and media type. The body is:

  1. The named example, when the request sends Prefer: example=<name>.
  2. Otherwise the first example in the document.
  3. Otherwise a value built from the response schema. The same schema always gives the same value.

Errors​

Errors use the problem details format (application/problem+json).

StatusWhen
400The path, query, headers or body do not match the operation. Each problem lists a JSON pointer.
401The key is missing, wrong or revoked.
404No operation matches the path.
405The path exists but not for this method. The Allow header lists the methods.
413The body is larger than the allowed size.
415The body's media type is not one the operation accepts.
428A PUT, PATCH or DELETE has no If-Match and the operation declares a 428 response.
429Too many requests for this key. Retry-After gives the seconds to wait.

Your administrator sets the body size and the request rate for each key.

For the reference docs of a version, see Reference docs.