REST API clients for development

During development, it is useful to send requests to the MiaRec server from a REST API client and inspect the responses before you write code.

API Explorer

Every MiaRec web server serves an interactive API Explorer at https://{your-miarec-server}/api/v2. It lists all endpoints with their parameters and schemas, and lets you send requests from the browser. See API Explorer.

cURL

cURL is a command-line tool for transferring data over HTTP and other protocols. It is available on Linux, macOS, and Windows.

Retrieve a list of users:

curl -u apiuser:secret https://{your-miarec-server}/api/v2/users.json

Sample response:

{
    "users": [{
        "name": "John Smith",
        "user_id": "e011c408-f288-11e4-9b73-e03f497dbdff",
        ...
    },{
        "name": "Marry Smith",
        "user_id": "34c7f1f6-9201-11e5-a739-e03f497dbdff",
        ...
    }],
    "total": null,
    "next_url": "/api/v2/users.json?limit=20&start=20"
}

Create a user from a JSON file:

curl -u apiuser:secret -H "Content-Type: application/json" -X POST \
    --data "@add_user.json" https://{your-miarec-server}/api/v2/users.json

Show the response headers, for example to inspect the rate limit headers:

curl -u apiuser:secret -i https://{your-miarec-server}/api/v2/users.json?limit=1

Desktop REST clients

Desktop clients such as Postman, Insomnia, and Bruno let you build and save requests in a graphical interface. Most of them can import the OpenAPI specification from https://{your-miarec-server}/api/v2/miarec-api-v2.yaml and generate a request collection for every endpoint. Configure Basic Auth with the login and password of the API user.