This version introduced improved response and request formats and added endpoints for uploading and managing user files.

Changes List

The following changes have been implemented compared to the beta version:

No Item Wrappers

Items are no longer wrapped into containers. The type of an item is now determined by the collection it resides in. All collections are now homogeneous and contain only items of the same type.

Version 1.0 beta response format

{
    "result":"success",
    "users":[
        {"user":{
            "id": 123,
            ...
        }},
        {"user":{
            "id": 456,
            ...
        }}
    ],
    "metadata": {...}
}

Version 1.0 response format

{
    "result":"success",
    "users":[
        {
            "id": 123,
            ...
        },
        {
            "id": 456,
            ...
        }
    ],
    "metadata": {...}
}

Associated Items Are Always Objects

By default the API used to 'simplify' item associations by converting them from objects into numeric identifiers, hence allowing an association to be either an object or an integer. Starting from this version all associated items are always represented as objects.

Version 1.0 beta response format

{
    "result":"success",
    "users":[
        {"user":{
            "id": 123,
            "account": 22
            ...
        }},
        ...
    ],
    "metadata": {...}
}

Version 1.0 response format

{
    "result":"success",
    "users":[
        {
            "id": 123,
            "account": {
                "id": 22
            }
            ...
        },
        ...
    ],
    "metadata": {...}
}

NOTE: In POST and PATCH requests associated items must not have any fields but id.

Items Are Always Wrapped into Collections

The request and response formats was unified for collection (e.g. /users) and item (e.g. /users/123) endpoints. Both endpoint types now accept and return only collections of items.

Version 1.0 beta response format

{
    "response": "success",
    "user": {
        "id": 123,
        "companyName": "...",
        "account": 22
    }
}

Version 1.0 response format

{
    "response": "success",
    "users": [
        {
            "id": 123,
            "companyName": "...",
            "account": {
                "id": 22
            }
        }
    ],
    "metadata": {...}
}

No Partial-Success Responses

An API request is now atomic. The request will succeed if and only if all its items pass validation. When any item from the request fails validation, the whole request fails and no items from it get processed by the API Server.

Version 1.0 beta response format

{
    "result": "partial-success",
    "users": [
        {"user": {
            "id": 123,
            ...
        }},
        {"failure": {
            "rawData": {...},
            "errors": [...]
        }}
    ],
    "metadata": {...}
}

Version 1.0 response format

{
    "result": "failure",
    "failures": [
        {
            "rawData": {...},
            "errors": [...]
        }
    ],
    "metadata": {...}
}

More and Better Metadata

The metadata property is now always present in non-error response objects and its format is unified for all non-GET responses.

Version 1.0 beta response format

{
    "result": "partial-success",
    "users": [
        {"user": {...}},
        {"failure": {...}},
        {"failure": {...}},
        {"user": {...}}
    ],
    "metadata": {
        "itemsReceivedCount": 4,
        "itemsCreatedCount": 2,
        "itemsFailedCount": 2,
        "failedItems": [
            1,
            2
        ]
    }
}

Version 1.0 response format

{
    "result": "failure",
    "failures": [
        {...},
        {...}
    ],
    "metadata": {
        "receivedItemsCount": 4,
        "validItems": [
            0,
            3
        ],
        "invalidItems": [
            1,
            2
        ]
    }
}

NOTE: invalidItems property will contain an empty array [] if all items have passed validation.

X-Version Header

The API Server now requires that the requests include the X-Version header.

Version 1.0 beta request

POST /users HTTP/1.1
Host: api.geoop.com
Authorization: Bearer oJ_7Hj.f-F3f.kL
Content-Type: application/json

{...}

Version 1.0 request

POST /users HTTP/1.1
Host: api.geoop.com
Authorization: Bearer oJ_7Hj.f-F3f.kL
Content-Type: application/json
X-Version: 1.0

{...}

Simplified Error Response

The error response object now only includes a single error item.

Version 1.0 beta response format

{
    "result": "error",
    "errors": [
        {"error": {
            type: "general",
            code: 1336,
            message: "..."
        }}
    ]
}

Version 1.0 response format

{
    "result": "error",
    "error": {
        type: "client",
        code: 1336,
        message: "..."
    }
}

More and Better HTTP Response Codes

The response (status) codes have been updated to provide more information to the client. The full list of codes and descriptions is available on the API Responses page.

Version 1.0 beta response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "result": "error",
    "errors": [...]
}

Version 1.0 response

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version: 1.0

{
    "result": "error",
    "error": {...}
}

No Nested Endpoints

The nested endpoints are no longer valid.

The /jobs/statuses, /jobs/visits, and /users/workgroups endpoints have been renamed into /statuses, /visits, and /workgroups, respectively.