API Overview

General notes

All pages of the API documentation describe how one entity looks. This does not include the links that are generated by Spring HATEOAS.

Date format

Dates can be in the format of a timestamp, 'yyyy-MM-dd' or 'yyyy-MM-dd HH:mm:ss'.

Links

Some entities have links to other entities. You always find the links in the "_links" property. A link always has a field "href" that can be used to access the linked resource.

employee = {
    ...,
    "_links": {
        "credential": {
            "href": "http://localhost:8080/api/employee/1/credential"
        }
    }
}

If you want to change the link on an entity please read the Spring Data REST documentation. Basically, you can PUT, POST and DELETE on links. PUT and POST need the content type text/uri-list and you send the href of the other resource as the request body.

Projections

Sometimes it is cumbersome to fetch linked resources via links. For these cases there are projections defined that embed a linked resource into the response.

% > curl localhost:8080/api/billableTimes/1?projection=withProject
{
    ...,
    "project": {
        "id": 12,
        "identifier": ...
    }
}

PUT vs PATCH

All entities that are updateable via PUT are also updateable via PATCH. With PATCH you can just send the fields you want to edit.

% > curl -X PATCH -d "{\"firstName\": \"John\"}" -H "Content-Type: application/json" localhost:8080/api/employees/1

Discoverability

Most of the API is discoverable. What does that mean? A response contains not only the data but also possible links that you can follow. Even the root of the API shows you what is available.

Caveat: Only Spring Data REST exported controllers are self-documented like that.

% > curl localhost:8080/api/
"api": {
    "_links": {
        "credentials": {
            "href": "http://localhost:8080/api/credentials{?page,size,sort}",
            "templated": true
        },
        "contactPersons": {
            "href": "http://localhost:8080/api/contactPersons{?page,size,sort}",
            "templated": true
        },...
    }
}

% > curl localhost:8080/api/credentials/
{
"_links": {
    "self": {
        "href": "http://localhost:8080/api/credentials{?page,size,sort}",
        "templated": true
    },
    "search": {
        "href": "http://localhost:8080/api/credentials/search"
    }
},
"_embedded": {
    "credentials": [
        {
            "id": 0,
            "email": "admin@techdev.de",
            "enabled": true,
            "_links": {
                "self": {
                    "href": "http://localhost:8080/api/credentials/0"
                },
                "employee": {
                    "href": "http://localhost:8080/api/credentials/0/employee"
                },
                "authorities": {
                    "href": "http://localhost:8080/api/credentials/0/authorities"
                }
            }
        },...
    ]
}
}

As you see, this is fairly self explanatory. But be careful: These links do not evaluate if you are allowed to access them so you might get a 403.

Pageable GET requests.

All requests marked with pageable in the parameters section take the following arguments: