Requests
This page covers the headers, the body as JSON, and the query parameters. What an entity, an attribute or a value must look like is on the other pages in this section.
HTTP headers
A request with a body declares its Content-Length. Without one the answer is a bare 411. A malformed or zero length gets InvalidRequest.
Content-Type is application/json or application/ld+json, and a merge operation also takes application/merge-patch+json. Batch operations take only the first two. Any other type, or none at all, gets a bare 415.
Accept is negotiated over application/json, application/ld+json and application/geo+json, with their wildcards and quality values. Only Retrieve Entity and Query Entities offer application/geo+json. When nothing acceptable is left, the answer is 406, and its body lists what the endpoint does offer.
A Link header follows web linking. The target is a valid IRI reference in angle brackets, rel is present, type is a media type and profile is an absolute IRI.
NGSILD-Tenant follows the tenant name rule under Andromeda's own bounds. Tenants covers an unknown tenant and a broker without multi-tenancy.
A malformed NGSILD-Snapshot header is refused.
Request bodies
A body that isn't valid JSON gets InvalidRequest, and trailing content after the JSON value makes it invalid. An empty array as the body is refused too.
A number outside the range Andromeda stores exactly is refused, and the error gives its JSON path. See Numbers.
An object that names the same member twice is refused at the repeated member, in every body. JSON leaves the meaning of a repeated name undefined, and keeping either value would silently lose the other. For the same reason, a member name starting with $serde_json::private:: is refused, because Andromeda's JSON reader reserves that prefix.
Structures the specification defines in full refuse members it doesn't define. That holds for the Query body, which must also carry "type": "Query", and for temporalQ, aggrParams, entity selectors, registration management, Subscriptions (see Subscriptions), Snapshots and EntityMaps.
Query parameters
Every endpoint refuses an unknown query parameter with InvalidRequest, even an endpoint that takes no parameters at all. If ?limitt=1000 were ignored, you would get the answer to a different question from the one you asked.
options and format take only the tokens the operation defines, matched case-sensitively. InvalidRequest goes to an unknown token, a token that is valid on another operation but not this one, a repeated token, and two representations that conflict, such as normalized,concise. keyValues and simplified are the same token, so naming both counts as a repeat.
A query that narrows nothing is refused as too wide. A type, an attribute list, q, a geoquery, id or local=true is enough to narrow it.
Projections exclude each other. pick and omit can't be used together, and attrs can't be used with either of them or name id or type. A linked entity term in pick, omit or q needs join, and it can't reach deeper than joinLevel (see Linked entities).
limit and offset are non-negative integers, and limit=0 is accepted only with count=true. cursor can't be used with offset or orderBy (see Pagination).
id and containedBy hold URIs, and idPattern can't be empty.
A q expression follows the q grammar, and anything outside it is BadRequestData. That includes a syntax error, a bare word, and a malformed number, DateTime, Date, Time or pattern. Strings use the standard JSON escapes and no others. Query language has the grammar, what each term compares, and the few places where Andromeda reads past the grammar.
type follows the Entity Type Selection grammar. Names are joined by | or ,, and a conjunction ; appears only inside parentheses, as in (Home;Vehicle)|Motorhome. Anything else is BadRequestData. Spaces between names and operators are skipped. type=* selects every type and keeps the query local, so entity queries and purges refuse it together with local=false.
Patterns (idPattern, ~= and !~=) use the IEEE 1003.2 regular expression dialect. Andromeda refuses anything outside it, including the following.
- Unicode classes such as
\p{...} - word boundaries and
\z - hexadecimal and octal escapes
- named groups
- flags other than
i,m,sandx - a repetition count over 255
- class set operations
- a range that ends in a character class
- a malformed or unknown character class name, such as
[[:alpha]] - an equivalence class or collating symbol that names more than one character, such as
[[.hyphen.]]
georel, geometry and coordinates are given together or not at all. near takes exactly one of maxDistance or minDistance, and the distance is positive and finite. Giving both needs the near_distance_band extension. No other relation takes a modifier. The expression has no whitespace or empty segments, and relation and geometry names are case-sensitive.
timerel is before, after or between, and it needs timeAt. between also needs endTimeAt. timeproperty names a temporal property. A temporal query needs timerel, timeAt and something that narrows it. Temporal orderBy takes only id.
When aggregatedValues is the representation a temporal query asks for, aggrMethods is required. format wins over options, so when options names aggregatedValues but format names another representation, the aggregation parameters are ignored. When neither names aggregatedValues, aggrMethods and aggrPeriodDuration are refused. Each method in aggrMethods is one the specification defines, and it has to apply to the recorded values of every requested attribute (see Temporal aggregation). aggrPeriodDuration is an ISO 8601 duration.
lang follows the rules under Language tags.