You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/api.md
+217-3Lines changed: 217 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,6 +34,9 @@ Here major and breaking changes to the API are listed by version.
34
34
35
35
### ODK Central v2023.2
36
36
37
+
**Added**:
38
+
- New [OData Dataset Service](#reference/odata-endpoints/odata-dataset-service) for each `Dataset` that provides a list of `Entities`.
39
+
37
40
**Changed**:
38
41
- The response of `GET`, `POST`, `PUT` and `PATCH` methods of [Submissions](#reference/submissions/listing-all-submissions-on-a-form) endpoint has been updated to include metadata of the `currentVersion` of the Submission.
39
42
@@ -3428,15 +3431,15 @@ While OData itself supports data of any sort of structure, Power BI and Tableau
3428
3431
3429
3432
In general, the OData standard protocol consists of three API endpoints:
3430
3433
3431
-
* The **Service Document** describes the available resources in the service. We provide one of these for every `Form` in the system. In our case, these are the tables we derive from the `repeat`s in the given Form. The root table is always named `Submissions`.
3434
+
* The **Service Document** describes the available resources in the service. We provide one of these for every `Form` in the system. As of version 2023.2, we also provide one for every `Dataset`.
3432
3435
* The **Metadata Document** is a formal XML-based EDMX schema description of every data object we might return. It is linked in every OData response.
3433
-
* The actual data documents, linked from the Service Document, are a simple JSON representation of the submission data, conforming to the schema we describe in our Metadata Document.
3436
+
* The actual data documents, linked from the Service Document, are a simple JSON representation of the submission data or entity, conforming to the schema we describe in our Metadata Document.
3434
3437
3435
3438
As our focus is on the bulk-export of data from ODK Central so that more advanced analysis tools can handle the data themselves, we do not support most of the features at the Intermediate and above conformance levels, like `$sort` or `$filter`.
3436
3439
3437
3440
## OData Form Service [/v1/projects/{projectId}/forms/{xmlFormId}.svc]
3438
3441
3439
-
ODK Central presents one OData service for every `Form` it knows about. Each service might have multiple tables related to that Form. To access the OData service, simply add `.svc` to the resource URL for the given Form.
3442
+
ODK Central presents one OData service for every `Form` it knows about. To access the OData service, simply add `.svc` to the resource URL for the given Form.
3440
3443
3441
3444
+ Parameters
3442
3445
+ projectId: `7` (number, required) - The numeric ID of the Project
@@ -3658,6 +3661,217 @@ Because this `/#/dl` path returns a web page that causes a file download rather
3658
3661
3659
3662
(html markup data)
3660
3663
3664
+
3665
+
## OData Dataset Service [/v1/projects/{projectId}/datasets/{name}.svc]
3666
+
3667
+
ODK Central presents one OData service for every `Dataset` as a way to get an OData feed of `Entities`. To access the OData service, simply add `.svc` to the resource URL for the given Dataset.
3668
+
3669
+
+ Parameters
3670
+
+ projectId: `7` (number, required) - The numeric ID of the Project
3671
+
3672
+
+`name`: `trees` (string, required) - The `name` of the `Dataset` whose OData service you wish to access.
3673
+
3674
+
### Service Document [GET]
3675
+
3676
+
The Service Document provides a link to the main source of information in this OData service: the list of `Entities` in this `Dataset`, as well as the Metadata Document describing the schema of this information.
The Metadata Document describes, in [EDMX CSDL](http://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html), the schema of all the data you can retrieve from the OData Dataset Service in question. Essentially, these are the Dataset properties, or the schema of each `Entity`, translated into the OData format.
### Data Document [GET /v1/projects/{projectId}/datasets/{name}.svc/Entities{?%24skip,%24top,%24count,%24filter,%24select}]
3784
+
3785
+
A data document is the straightforward JSON representation of all the `Entities` in a `Dataset`.
3786
+
3787
+
The `$top` and `$skip` querystring parameters, specified by OData, apply `limit` and `offset` operations to the data, respectively. The `$count` parameter, also an OData standard, will annotate the response data with the total row count, regardless of the scoping requested by `$top` and `$skip`. While paging is possible through these parameters, it will not greatly improve the performance of exporting data. ODK Central prefers to bulk-export all of its data at once if possible.
3788
+
3789
+
The [`$filter` querystring parameter](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948)can be used to filter by any data field in the system-level schema, but not the Dataset properties. The operators `lt`, `le`, `eq`, `ne`, `ge`, `gt`, `not`, `and`, and `or` are supported. The built-in functions `now`, `year`, `month`, `day`, `hour`, `minute`, `second` are supported.
Note that `createdAt` is a time component. This means that any comparisons you make need to account for the full time of the entity. It might seem like `$filter=__system/createdAt le 2020-01-31` would return all results on or before 31 Jan 2020, but in fact only entities made before midnight of that day would be accepted. To include all of the month of January, you need to filter by either `$filter=__system/createdAt le 2020-01-31T23:59:59.999Z` or `$filter=__system/createdAt lt 2020-02-01`. Remember also that you can [query by a specific timezone](https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC).
3802
+
3803
+
Please see the [OData documentation](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948) on `$filter`[operations](http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_BuiltinFilterOperations) and [functions](http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_BuiltinQueryFunctions) for more information.
3804
+
3805
+
The [`$select` query parameter](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358942) will return just the fields you specify and is supported on `__id`, `__system`, `__system/creatorId` and `__system/createdAt`, as well as on user defined properties.
3806
+
3807
+
As the vast majority of clients only support the JSON OData format, that is the only format ODK Central offers.
3808
+
3809
+
+ Parameters
3810
+
+`%24skip`: `10` (number, optional) - If supplied, the first `$skip` rows will be omitted from the results.
3811
+
+`%24top`: `5` (number, optional) - If supplied, only up to `$top` rows will be returned in the results.
3812
+
+`%24count`: `true` (boolean, optional) - If set to `true`, an `@odata.count` property will be added to the result indicating the total number of rows, ignoring the above paging parameters.
3813
+
+`%24filter`: `year(__system/createdAt) lt year(now())` (string, optional) - If provided, will filter responses to those matching the query. Only [certain fields](/reference/odata-endpoints/odata-form-service/data-document) are available to reference. The operators `lt`, `le`, `eq`, `neq`, `ge`, `gt`, `not`, `and`, and `or` are supported, and the built-in functions `now`, `year`, `month`, `day`, `hour`, `minute`, `second`.
3814
+
+`%24select`: `__id, label, name` (string, optional) - If provided, will return only the selected fields.
0 commit comments