API Overview

The ChamberForge API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the ChamberForge API on the test server which doesn't affect your live data. To request access to the test server, please contact us at support@chamberforge.com.

The ChamberForge API doesn't support bulk updates. You can work on only one object per request.

Authentication

The ChamberForge API uses API keys to authenticate requests. If you have developer access, you can view and manage your API keys in the ChamberForge Dashboard under My Account, Developer screen.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

REST API Success Responses

1- GET - Get single item - HTTP Response Code: 200

HTTP/1.1  200
Content-Type: application/json

{
    "id": 10,
    "name": "shirt",
    "color": "red",
    "price": "3"
},

2- GET - Get item list - HTTP Response Code: 200

HTTP/1.1 200
Content-Type: application/json

[
    {
        "id": 10,
        "name": "shirt",
        "color": "red",
        "price": "3"
    },
    {
        "id": 11,
        "name": "coat",
        "color": "black",
        "price": "00"
    }
]

3- POST - Create a new item - HTTP Response Code: 201

HTTP/1.1 201
Content-Type: application/json

    {
        "id": 11,
        "name": "coat",
        "color": "black",
        "price": "00"
    }

4- PUT/PATCH - Update an item - HTTP Response Code: 200/204

HTTP/1.1 200
Content-Type: application/json

    {
        "id": 11,
        "name": "coat",
        "color": "black",
        "price": "00"
    }

5- DELETE - Delete an item - HTTP Response Code: 204

HTTP/1.1 204

Errors

ChamberForge uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with ChamberForge's servers (these are rare).

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.

Status Code Type Description
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
402 Request Failed The parameters were valid but the request failed.
403 Forbidden The API key doesn't have permissions to perform the request.
404 Not Found The requested resource doesn't exist.
429 Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 Server Errors Something went wrong on ChamberForge's end. (These are rare.)

REST API Error Responses

1- GET - HTTP Response Code: 404

HTTP/1.1  404
Content-Type: application/json

{
    "message": "The item does not exist"
}

2- DELETE - HTTP Response Code: 404

HTTP/1.1  404
Content-Type: application/json

{
    "message": "The item does not exist"
}

3- POST - HTTP Response Code: 400

HTTP/1.1  400
Content-Type: application/json

{
    "message": "Validation errors in your request", /* skip or optional error message */
    "errors": [
        {
            "message": "Oops! The value is invalid",
            "code": 34,
            "field": "email"
        }
    ]
}

HTTP/1.1  404
Content-Type: application/json

{
    "message": "The item does not exist"
}

4- PUT - HTTP Response Code: 400/404

HTTP/1.1  404
Content-Type: application/json

{
    "message": "The item does not exist"
}