Skip to content

Commit f6dcd6d

Browse files
marie-xmarie-x
committed
establish bulk POST conventions
1 parent 9530e1e commit f6dcd6d

2 files changed

Lines changed: 129 additions & 68 deletions

File tree

‎agency/README.md‎

Lines changed: 124 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ This specification uses data types including timestamps, UUIDs, and vehicle stat
2727

2828
### Versioning
2929

30-
`agency` APIs must handle requests for specific versions of the specification from clients.
30+
`Agency` APIs must handle requests for specific versions of the specification from clients.
3131

3232
Versioning must be implemented as specified in the [Versioning section][versioning].
3333

@@ -82,90 +82,133 @@ _No content returned on vehicle not found._
8282

8383
## Vehicle - Register
8484

85-
The `/vehicles` registration endpoint is used to register a vehicle for use in the Agency's jurisdiction.
85+
The `/vehicles` registration endpoint is used to register vehicles for use in the Agency's jurisdiction.
8686

87-
Endpoint: `/vehicles`
88-
Method: `POST`
87+
**Endpoint**: `/vehicles`
88+
**Method:** `POST`
89+
**Payload:** An array of [Vehicles](#vehicle)
8990

90-
Body Params:
91+
200 Success Response:
9192

92-
TODO a list of Vehicle records FIXME
93+
| Field | Type | Field Description |
94+
| ----- | ---- | ----------------- |
95+
| `total` | Integer | Total number of provided vehicles |
96+
| `success` | Integer | Number of successfully written vehicles |
97+
| `failures` | [InvalidVehicle](#invalid-vehicle-record)[] | Array of failure responses (empty if all successful) |
9398

94-
200 Success Response:
99+
### Invalid Vehicle Record:
95100

96-
_No content returned on success._
101+
| Field | Type | Field Description |
102+
| ----- | ---- | ----------------- |
103+
| `vehicle` | Vehicle | Invalid vehicle record |
104+
| `errors` | [VehicleError](#vehicle-error-record)[] | Description of why vehicle record is invalid |
97105

98-
400 Failure Response:
106+
### Vehicle Error Record:
99107

100-
| `error` | `error_description` | `error_details`[] |
101-
| -------------------- | ------------------------------------------------- | ------------------------------- |
102-
| `bad_param` | A validation error occurred. | Array of parameters with errors |
103-
| `missing_param` | A required parameter is missing. | Array of missing parameters |
108+
| Field | Type | Field Description |
109+
| ----- | ---- | ----------------- |
110+
| `error` | [VehicleErrorType](#vehicle-error-types) | Type of error |
111+
| `error_details` | String[] | Array of fields with errors, if applicable |
104112

105-
409 Failure Response:
113+
### Vehicle Errors:
106114

107115
| `error` | `error_description` | `error_details`[] |
108116
| -------------------- | ------------------------------------------------- | ------------------------------- |
117+
| `bad_param` | A validation error occurred | Array of parameters with errors |
118+
| `missing_param` | A required parameter is missing | Array of missing parameters |
109119
| `already_registered` | A vehicle with `device_id` is already registered | |
110120

121+
403 Unauthorized Response:
122+
123+
**None**
124+
111125
[Top][toc]
112126

113127
## Vehicles - Events
114128

115129
The vehicle `/events` endpoint allows the Provider to submit events describing the state changes of multiple vehicles.
116130

117-
Endpoint: `/vehicles/events`
131+
**Endpoint:** `/vehicles/events`
132+
**Method:** `POST`
133+
**Payload:** An array of [Vehicle Events](#vehicle-event)
118134

119-
Method: `POST`
135+
200 Success Response:
120136

121-
Body Params:
137+
| Field | Type | Field Description |
138+
| ----- | ---- | ----------------- |
139+
| `total` | Integer | Total number of provided events |
140+
| `success` | Integer | Number of successfully written events |
141+
| `failures` | [InvalidVehicle](#invalid-vehicle-record)[] | Array of failure responses (empty if all successful) |
122142

123-
| Field | Type | Required/Optional | Field Description |
124-
|-----------------|------------------------------|------------------------|------------------------------------------------------------------------------------------------------------|
125-
| `events` | [EventData](#vehicle-event-data)[] | Required | An array of [Vehicle Event Data](#vehicle-event-data) objects. |
143+
### Invalid Event Record:
126144

127-
200 Success Response:
145+
| Field | Type | Field Description |
146+
| ----- | ---- | ----------------- |
147+
| `event` | [Event](#vehicle-event) | Invalid event record |
148+
| `errors` | [EventError](#event-error-record)[] | Details of why event record is invalid |
128149

129-
| Field | Type | Field Description |
130-
| ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
131-
| `success` | Integer | Number of successfully written events. |
132-
| `total` | Integer | Total number of provided events. |
133-
| `failures` | [EventData](#vehicle-event-data)[] | Array of invalid events (empty if all successful). |
150+
### Event Error Record:
134151

135-
(?) Should we have a description/error-code for each failure in the `failures`?
152+
| Field | Type | Field Description |
153+
| ----- | ---- | ----------------- |
154+
| `error` | [EventErrorType](#event-errors) | Type of error |
155+
| `error_details` | String[] | Array of fields with errors, if applicable |
136156

137-
400 Failure Response:
157+
### Event Errors:
158+
159+
| `error` | `error_description` | `error_details`[] |
160+
| -------------------- | ------------------------------------------------- | ------------------------------- |
161+
| `bad_param` | A validation error occurred | Array of parameters with errors |
162+
| `missing_param` | A required parameter is missing | Array of missing parameters |
163+
| `unregistered` | This `device_id` is unregistered | |
164+
165+
403 Unauthorized Response:
138166

139-
| `error` | `error_description` | `error_details`[] |
140-
| ------------------- | ------------------------------- | ------------------------------- |
141-
| `bad_param` | A validation error occurred | Array of parameters with errors |
142-
| `missing_param` | A required parameter is missing | Array of missing parameters |
143-
| `unregistered` | Some of the devices are not registered | |
167+
**None**
144168

145169
[Top][toc]
146170

147171
## Vehicles - Telemetry
148172

149173
The vehicle `/telemetry` endpoint allows a Provider to send vehicle telemetry data in a batch for any number of vehicles in the fleet.
150174

151-
Endpoint: `/vehicles/telemetry`
152-
Method: `POST`
175+
**Endpoint**: `/vehicles/telemetry`
176+
**Method**: `POST`
177+
**Payload**: An array of [Vehicle Telemetry][vehicle-telemetry]
153178

154-
Body Params:
179+
200 Success Response:
155180

156-
| Field | Type | Required/Optional | Field Description |
157-
| ------------- | ------------------------------ | ----------------- | -------------------------------------------------------------------------------------- |
158-
| `telemetries` | [Telemetry](#telemetry-data)[] | Required | Array of telemetry for one or more vehicles. |
181+
| Field | Type | Field Description |
182+
| ----- | ---- | ----------------- |
183+
| `total` | Integer | Total number of provided telemetry entries |
184+
| `success` | Integer | Number of successfully written telemetry entries |
185+
| `failures` | [InvalidTelemetry](#invalid-telemetry-record)[] | Array of failure responses (empty if all successful) |
159186

160-
200 Success Response:
187+
### Invalid Telemetry Record:
161188

162-
| Field | Type | Field Description |
163-
| ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
164-
| `success` | Integer | Number of successfully written telemetry data points. |
165-
| `total` | Integer | Total number of provided points. |
166-
| `failures` | [Telemetry Error](#telemetry-error)[] | Array of errors including the failed telemetry data and error details (empty if all successful). |
189+
| Field | Type | Field Description |
190+
| ----- | ---- | ----------------- |
191+
| `event` | [Event](#vehicle-telemetry) | Invalid telemetry record |
192+
| `errors` | [TelemetryError](#telemetry-error-record)[] | Details of why telemetry record is invalid |
193+
194+
### Event Error Record:
195+
196+
| Field | Type | Field Description |
197+
| ----- | ---- | ----------------- |
198+
| `error` | [TelemetryErrorType](#telemetry-errors) | Type of error |
199+
| `error_details` | String[] | Array of fields with errors, if applicable |
200+
201+
### Telemetry Errors:
202+
203+
| `error` | `error_description` | `error_details`[] |
204+
| -------------------- | ------------------------------------------------- | ------------------------------- |
205+
| `bad_param` | A validation error occurred | Array of parameters with errors |
206+
| `missing_param` | A required parameter is missing | Array of missing parameters |
207+
| `unregistered` | This `device_id` is unregistered | |
167208

168-
Alway returns 200. Any failed data is detailed in the `failures` array of the response.
209+
403 Unauthorized Response:
210+
211+
**None**
169212

170213
[Top][toc]
171214

@@ -176,22 +219,44 @@ The `/stops` endpoint allows an agency to register city-managed Stops, or a prov
176219
**Endpoint:** `/stops`
177220
**Method:** `POST`
178221
**[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638)
179-
**Request Body**: An array of [Stops][stops]
222+
**Payload**: An array of [Stops][stops]
180223

181224
200 Success Response:
182225

183-
_No content returned on success._
226+
| Field | Type | Field Description |
227+
| ----- | ---- | ----------------- |
228+
| `total` | Integer | Total number of provided telemetry entries |
229+
| `success` | Integer | Number of successfully written telemetry entries |
230+
| `failures` | [InvalidTelemetry](#invalid-telemetry-record)[] | Array of failure responses (empty if all successful) |
184231

185-
(?) TODO FIXME resolve bulk return codes
232+
### Invalid Telemetry Record:
186233

187-
400 Failure Response:
234+
| Field | Type | Field Description |
235+
| ----- | ---- | ----------------- |
236+
| `event` | [Event](#vehicle-telemetry) | Invalid telemetry record |
237+
| `errors` | [TelemetryError](#telemetry-error-record)[] | Details of why telemetry record is invalid |
238+
239+
### Event Error Record:
240+
241+
| Field | Type | Field Description |
242+
| ----- | ---- | ----------------- |
243+
| `error` | [TelemetryErrorType](#telemetry-errors) | Type of error |
244+
| `error_details` | String[] | Array of fields with errors, if applicable |
245+
246+
### Telemetry Errors:
188247

189248
| `error` | `error_description` | `error_details`[] |
190249
| -------------------- | ------------------------------------------------- | ------------------------------- |
191-
| `bad_param` | A validation error occurred. | Array of parameters with errors |
192-
| `missing_param` | A required parameter is missing. | Array of missing parameters |
250+
| `bad_param` | A validation error occurred | Array of parameters with errors |
251+
| `missing_param` | A required parameter is missing | Array of missing parameters |
252+
| `unregistered` | This `device_id` is unregistered | |
253+
254+
403 Unauthorized Response:
255+
256+
**None**
257+
258+
[Top][toc]
193259

194-
409 Failure Response:
195260

196261
| `error` | `error_description` | `error_details`[] |
197262
| -------------------- | ------------------------------------------------- | ------------------------------- |
@@ -200,7 +265,7 @@ _No content returned on success._
200265
**Endpoint:** `/stops`
201266
**Method:** `PUT`
202267
**[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638)
203-
**Request Body**: An array of subsets of [Stop][stops] information, where the permitted subset fields are defined as:
268+
**Payload**: An array of subsets of [Stop][stops] information, where the permitted subset fields are defined as:
204269

205270
| Field | Required/Optional | Description |
206271
|---------------------|-------------------|---------------------------------------------|
@@ -226,7 +291,7 @@ _No content returned if no vehicle matching `stop_id` is found._
226291
**Endpoint:** `/stops/:stop_id`
227292
**Method:** `GET`
228293
**[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638)
229-
**Payload:** `{ "stops": [] }`, an array of [Stops][stops]
294+
**Payload:** An array of [Stops][stops]
230295

231296
Path Params:
232297

@@ -250,7 +315,7 @@ The Trips endpoint serves two purposes:
250315
**Endpoint:** `/trips`
251316
**Method:** `POST`
252317
**[Beta feature][beta]:** No (as of 2.0.0)
253-
**Payload:** `{ "trips": [] }`, an array of [Trips](#trip-data)
318+
**Payload:** Array of [Trips](#trip-data)
254319

255320
Body Params:
256321

@@ -289,9 +354,11 @@ Body Params:
289354
[trip-data]: /general-information.md#trips
290355
[toc]: #table-of-contents
291356
[ts]: /general-information.md#timestamps
357+
[vehicle]: /data-types.md#vehicles
292358
[vehicle-types]: /general-information.md#vehicle-types
293359
[vehicle-states]: /modes/vehicle_states.md
294360
[vehicle-event-types]: /modes/event_types.md
295-
[vehicle-event-data]: /general-information.md#event-data
361+
[vehicle-event]: /data-types.md#events
362+
[vehicle-telemetry]: /data-types.md#telemetry
296363
[versioning]: /general-information.md#versioning
297364
[error-message]: /general-information.md#error-messages

0 commit comments

Comments
 (0)