API documentation

The API is based on DunglasApiBundle to generate a beautiful JSON-LD REST API with Hydra markups, if you do not know what it is about, check the bundle documentation it provides all the necessary links :).

The API follow the standard REST API guidelines, the specifications described bellow are more specific to a Symfony API or the use of the DunglasApiBundle bundle.

Contexts

If you make a request, you will find in the response a property @context with a URI. Contexts are an API endpoint where the properties of the entity are detailed.

For instance, if you have the following response:

{
    "@context": "\/api\/contexts\/ConstraintViolationList",
    "@type": "ConstraintViolationList",
    ...
}

It means that if you request /api/contexts/ConstraintViolationList, you will get all the properties and methods of the entity ConstraintViolationList:

{
    "@context": {
        "@vocab":"http:\/\/localhost:8080\/api\/vocab#",
        "hydra":"http:\/\/www.w3.org\/ns\/hydra\/core#"
    }
}

What the ****?!! Hey no panic! See the @vocab property? It tells you that what we are looking for is not here but gives the path to it. So let's request /api/vocab:

{
    ...
    "hydra:supportedClass": [
        ...
        {
            "@id": "#ConstraintViolationList",
            "@type": "hydra:Class",
            "subClassOf": "hydra:Error",
            "hydra:title": "A constraint violation list",
            "hydra:supportedProperty": [
                {
                    "@type": "hydra:SupportedProperty",
                    "hydra:property": {
                        "@id": "#ConstraintViolationList\/violation",
                        "@type": "rdf:Property",
                        "rdfs:label": "violation",
                        "domain": "#ConstraintViolationList",
                        "range": "#ConstraintViolation"
                    },
                    "hydra:title": "violation",
                    "hydra:description": "The violations",
                    "hydra:readable": true,
                    "hydra:writable": false
                }
            ]
        },
        ...
    ]
    ...
}

From it we can see that the ConstraintViolationList has ConstraintViolation properties, which is itself describe in this vocab file. Tedious? Hell yeah! That's why you can use HydraConsole, it does the job for you!

Still, if you are looking for the details of a class, in our case, start to look in the vocab first. If you do not like it, you can try to look the phpDoc.

Filters

Filters are applied on a given url by adding ?filter1&filter2 at the end, which gives the following URL: url?filter1&filter2.

The mechanism of filter is quite common although different implementations are possible. The available filters are given below. When a filter will be available for an API endpoint, you will find on which parameters you can use the filters in the Postman documentation.

Order filters

Order filters are used to order a collection by properties in ascending or descending orders.

Syntax:

url?filter[order][property]=<ASC|DESC>

where property is the name of the property and ASC, DESC the order value (case insensitive). The order of the order filters is important: if we specify the filter ?order[name]=asc&order[id]=desc, the result will be a collection ordered by name in ascending order and when some names are equal, ordered by id in descending order.

Of course it does not matter if another filter type is inserted between two order filters.

Where filters

Where filters are used to filter a collection by applying a mask (making match some properties).

Syntax:

url?filter[where][property][op]=value

where property is the name of the property, op the operator and value takes the value wished (case sensitive). The value is by default a string. If you wish to test a boolean value, test it against 0 (false) or 1 (true) - of course if the property is a number, it will be tested against a number and not against a boolean value! A null value is equaled to 0 (false).

Boolean values

To refer to a boolean value at false, use 0 and not false as a value. The same way use 1 for true.

Example: url?filter[where][property][op]=1

Date values

The date value is a date string format which must be understood by \DateTime.

Example: url?filter[where][property][op]=2015-04-28

Null values

To search for value null just use null!

Example: url?filter[where][property][op]=null

Note: this feature has a drawback, it becomes impossible to search for a string value "null".

Empty values

Careful here, an empty value for a REST API is not the same as an empty value in PHP. Indeed in PHP a value is empty if undefined, null or equivalent to false. For the API, and empty value is only the later:

• for a string: ""
• for a number: 0
• for a date: invalid, will throw an error
• for a boolean: false

To search for an empty value just omit the value:

Example: url?filter[where][property][op]= or url?filter[where][property][op] (the first one is builded as the second by your client).

Operators

Operator	Description
and	Logical AND operator
or	Logical OR operator
gt, gte	Numerical greater than (>); greater than or equal (>=). Valid only for numerical and date values. For Geopoint values, the units are in miles by default. See Geopoint for more information.
lt, lte	Numerical less than (<); less than or equal (<=). Valid only for numerical and date values. For geolocation values, the units are in miles by default. See Geopoint for more information.
between	True if the value is between the two specified values: greater than or equal to first value and less than or equal to second value. For geolocation values, the units are in miles by default. See Geopoint for more information.
neq	Not equal (!=)
like, nlike	LIKE / NOT LIKE operators for use with regular expressions. The regular expression format depends on the backend data source.

and/or

Example: find all entities for which title equal to 'My Post' and content to Hello.

REST syntax:

?filter[where][and][0][title]=My%20Post&filter[where][and][1][content]=Hello

And behind the scene will generate the following array for the query parameter:

[ 'filter' => [
    'where' => [
        'and' => [
            'title'   => 'My Post',
            'content' => 'Hello'
        ]
    ]
]

Note: the [0] and [1] are not mandatory. You can use []. However, if you do so, the order does matter.

Example: logical expression: (field1 === 'foo' && field2 === 'bar') || 'field1' === 'morefoo').

REST syntax:

?filter[where][or][0][and][0][field1]=foo&filter[where][or][0][and][1][field2]=bar&filter[where][or][1][field1]=morefoo

[ 'filter' => [
    'where' => [
        'or' => [
            'and' => [
                'field1' => 'foo',
                'field2' => 'bar'
            ],
            'field1' => 'morefoo'
        ]
    ]
]

gt(e)/lt(e)

Example: the following query returns all instances of the employee entity using a where filter that specifies a date property after (greater than) the specified date:

REST syntax:

/employees?filter[where][date][gt]=2014-04-01T18:30:00.000Z

The date value may be simplified. The format does not really matter but keep in mind that behind it, the value retrieved is instantiated as a \DateTime with the default timezone of the application.

between

Example of between operator: filter[where][price][between][0]=0&filter[where][price][between][1]=7.

like/nlike

The like and nlike (not like) operators enable you to match SQL regular expressions.

Fields validation

When you try to update or create a resource, some constraints may be applied to the form. In this case, a 400 response is returned with a ConstraintViolationList entity. All violations are found in the violations property and each object are an instance of ConstraintViolation (cf. vocab).