Conventions used throughout API

We are doing our best to develop an API that is consistent and adheres to commonly used best practices. The following conventions will be used across all API resources.

Rest endpoints

An endpoint name to manage a particular resource is created using the plural form of a noun describing that resource. The table below showcases a few examples:

Add a new resource

You can add a new resource or update an existing one using an http POST request. To add new resource POST resource object on /resource endpoint.

Here’s the syntax to add an offer using a POST request:

POST https://api.smartrecruiters.com/v1/offers

With a request body (notice there is no id in inserted object):

{
    "catalogId": "ab-32-gf-asd",
    "name": "Java Developer Skill Test",
    "description": "Senior Java Developer Test",
    "terms": {
        "type": "SKILLS_TEST",
        "price": {
            "amount": "20.00",
            "currencyCode": "USD"
        }
    }
}

Update existing resource

To update a resource, send a POST request on /resource/{resourceId} endpoint. Here’s the syntax to edit an existing offer:

POST https://api.smartrecruiters.com/v1/offers/511a3942300469a9c33819d8

With a request body (notice that id is provided):

{
    "id" : "511a3942300469a9c33819d8"
    "catalogId": "ab-32-gf-asd",
    "name": "Java Developer Skill Test",
    "description": "Senior Java Developer Test",
    "terms": {
        "type": "SKILLS_TEST",
        "price": {
            "amount": "20.00",
            "currencyCode": "USD"
        }
    }
}

Retrieve resources

Getting a single resource requires sending an http GET request to a proper endpoint. A resource ID has to be passed as a part of the URL.

GET https://api.smartrecruiters.com/v1/offers/511a3942300469a9c33819d8

Response body will contain the queried resource or an error object if the invocation fails.

List resources

Getting a list of resources involves invoking the http GET request on a specific endpoint without passing the resource id:

GET https://api.smartrecruiters.com/v1/offers

The number of results returned by such a call differs between endpoints. You can control the number of retrieved items by specifying values for offset and limit:

GET https://api.smartrecruiters.com/v1/offers?offset=30&limit=20

All other filtering parameters need to be specified as URL parameters:

GET https://api.smartrecruiters.com/v1/offers?status=ACTIVE

All lists returned by the API will be wrapped into a ListResult object. The ListResult object will have a limit, offset and totalFound number.

Paging

Resources paging can be implemented by using the offset, limit and totalFound properties of ListResult object. Let’s consider the following call:

GET https://api.smartrecruiters.com/v1/offers?status=ACTIVE

Below is a sample response body:

{
    "offset": 0,
    "limit": 10,
    "totalFound": 130,
    "content": [
        ...
    ]
}

This means that there are 130 resources found, out of which the response contains the first 10 (since offset is 0 and limit is 10). To get the next 10 resources, the following statement can be used:

GET https://api.smartrecruiters.com/v1/offers?status=ACTIVE&offset=10&limit=10

The response body for the above statement would be:

{
    "offset": 10,
    "limit": 10,
    "totalFound": 130,
    "content": [
        ...
    ]
}