Skip to content

Commit 1f4d197

Browse files
marie-xmarie-x
committed
consolidate bulk response info
1 parent f6dcd6d commit 1f4d197

3 files changed

Lines changed: 95 additions & 134 deletions

File tree

‎agency/README.md‎

Lines changed: 55 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,14 @@ This specification contains a collection of RESTful APIs used to specify the dig
1313
* [Responses and Error Messages](#responses-and-error-messages)
1414
* [Authorization](#authorization)
1515
* [Vehicles](#vehicles)
16-
* [Vehicle - Register](#vehicle---register)
17-
* [Vehicle - Update](#vehicle---update)
18-
* [Vehicle - Events](#vehicle---event)
19-
* [Vehicle - Telemetry](#vehicle---telemetry)
16+
* [Vehicle - Register](#vehicle---register)
17+
* [Vehicle - Update](#vehicle---update)
18+
* [Vehicle - Events](#vehicle---event)
19+
* [Vehicle - Telemetry](#vehicle---telemetry)
2020
* [Stops](#stops)
21+
* [Stops - Register](#stops---register)
22+
* [Stops - Update](#stops---update)
23+
* [Stops - Readback](#stops---readback)
2124

2225
## General information
2326

@@ -90,27 +93,9 @@ The `/vehicles` registration endpoint is used to register vehicles for use in th
9093

9194
200 Success Response:
9295

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) |
96+
See [Bulk Responses](#bulk-responses)
9897

99-
### Invalid Vehicle Record:
100-
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 |
105-
106-
### Vehicle Error Record:
107-
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 |
112-
113-
### Vehicle Errors:
98+
### Vehicle Register Error Codes:
11499

115100
| `error` | `error_description` | `error_details`[] |
116101
| -------------------- | ------------------------------------------------- | ------------------------------- |
@@ -122,6 +107,25 @@ The `/vehicles` registration endpoint is used to register vehicles for use in th
122107

123108
**None**
124109

110+
## Vehicle - Update
111+
112+
The `/vehicles` update endpoint is used to change vehicle information, should some aspect of the vehicle change, such as the `vehicle_id`. Each vehicle must already be registered.
113+
114+
**Endpoint**: `/vehicles`
115+
**Method:** `PUT`
116+
**Payload:** An array of [Vehicles](#vehicle)
117+
118+
200 Success Response:
119+
120+
See [Bulk Responses](#bulk-responses)
121+
122+
### Vehicle Update Error Codes:
123+
124+
| `error` | `error_description` | `error_details`[] |
125+
| -------------------- | ------------------------------------------------- | ------------------------------- |
126+
| `bad_param` | A validation error occurred | Array of parameters with errors |
127+
| `unregistered` | This `device_id` is unregistered | |
128+
125129
[Top][toc]
126130

127131
## Vehicles - Events
@@ -134,37 +138,15 @@ The vehicle `/events` endpoint allows the Provider to submit events describing t
134138

135139
200 Success Response:
136140

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) |
142-
143-
### Invalid Event Record:
144-
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 |
149-
150-
### Event Error Record:
151-
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 |
141+
See [Bulk Responses](#bulk-responses)
156142

157143
### Event Errors:
158144

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:
166-
167-
**None**
145+
| `error` | `error_description` | `error_details`[] |
146+
| ------- | ------------------- | ----------------- |
147+
| `bad_param` | A validation error occurred | Array of parameters with errors |
148+
| `missing_param` | A required parameter is missing | Array of missing parameters |
149+
| `unregistered` | This `device_id` is unregistered | |
168150

169151
[Top][toc]
170152

@@ -178,25 +160,7 @@ The vehicle `/telemetry` endpoint allows a Provider to send vehicle telemetry da
178160

179161
200 Success Response:
180162

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) |
186-
187-
### Invalid Telemetry Record:
188-
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 |
163+
See [Bulk Responses](#bulk-responses)
200164

201165
### Telemetry Errors:
202166

@@ -206,66 +170,39 @@ The vehicle `/telemetry` endpoint allows a Provider to send vehicle telemetry da
206170
| `missing_param` | A required parameter is missing | Array of missing parameters |
207171
| `unregistered` | This `device_id` is unregistered | |
208172

209-
403 Unauthorized Response:
210-
211-
**None**
212-
213173
[Top][toc]
214174

215175
## Stops
216176

177+
### Stops - Register
178+
217179
The `/stops` endpoint allows an agency to register city-managed Stops, or a provider to register self-managed Stops.
218180

219181
**Endpoint:** `/stops`
220182
**Method:** `POST`
221-
**[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638)
222183
**Payload**: An array of [Stops][stops]
223184

224185
200 Success Response:
225186

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) |
187+
See [Bulk Responses](#bulk-responses)
231188

232-
### Invalid Telemetry Record:
233-
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:
189+
#### Stops Register Errors:
247190

248191
| `error` | `error_description` | `error_details`[] |
249192
| -------------------- | ------------------------------------------------- | ------------------------------- |
250193
| `bad_param` | A validation error occurred | Array of parameters with errors |
251194
| `missing_param` | A required parameter is missing | Array of missing parameters |
252-
| `unregistered` | This `device_id` is unregistered | |
195+
| `already_registered` | A stop with `stop_id` is already registered | |
253196

254197
403 Unauthorized Response:
255198

256-
**None**
257-
258199
[Top][toc]
259200

260-
261-
| `error` | `error_description` | `error_details`[] |
262-
| -------------------- | ------------------------------------------------- | ------------------------------- |
263-
| `already_registered` | A stop with `stop_id` is already registered | |
201+
### Stops - Update
264202

265203
**Endpoint:** `/stops`
266204
**Method:** `PUT`
267-
**[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638)
268-
**Payload**: An array of subsets of [Stop][stops] information, where the permitted subset fields are defined as:
205+
**Payload**: An array of of [Stop][stops] information, where the permitted changable fields are defined as:
269206

270207
| Field | Required/Optional | Description |
271208
|---------------------|-------------------|---------------------------------------------|
@@ -275,22 +212,20 @@ The `/stops` endpoint allows an agency to register city-managed Stops, or a prov
275212

276213
200 Success Response:
277214

278-
_No content returned on success._
215+
See [Bulk Responses](#bulk-responses)
279216

280-
400 Failure Response:
217+
#### Stops update Errors:
281218

282219
| `error` | `error_description` | `error_details`[] |
283220
| -------------------- | ------------------------------------------------- | ------------------------------- |
284-
| `bad_param` | A validation error occurred. | Array of parameters with errors |
285-
| `missing_param` | A required parameter is missing. | Array of missing parameters |
286-
287-
404 Failure Response:
221+
| `bad_param` | A validation error occurred | Array of parameters with errors |
222+
| `missing_param` | A required parameter is missing | Array of missing parameters |
223+
| `unregisterd` | No stop with `stop_id` is already registered | |
288224

289-
_No content returned if no vehicle matching `stop_id` is found._
225+
### Stops - Readback
290226

291227
**Endpoint:** `/stops/:stop_id`
292228
**Method:** `GET`
293-
**[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638)
294229
**Payload:** An array of [Stops][stops]
295230

296231
Path Params:
@@ -314,34 +249,26 @@ The Trips endpoint serves two purposes:
314249

315250
**Endpoint:** `/trips`
316251
**Method:** `POST`
317-
**[Beta feature][beta]:** No (as of 2.0.0)
318252
**Payload:** Array of [Trips](#trip-data)
319253

320-
Body Params:
321-
322-
| Field | Type | Required/Optional | Field Description |
323-
| ------------- | ------------------------------ | ----------------- | -------------------------------------------------------------------------------------- |
324-
| `trips` | [Trip](#trip-data)[] | Required | Array of trip records
325-
326254
200 Success Response:
327255

328-
| Field | Type | Field Description |
329-
| ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
330-
| `success` | Integer | Number of successfully written trip records points |
331-
| `total` | Integer | Total number of provided points |
332-
| `failures` | [Trip](#trip-data)[] | Array of failed trip records (empty if all successful) |
256+
See [Bulk Responses](#bulk-responses)
333257

258+
### Trip Errors:
334259

335-
400 Failure Response:
336260
| `error` | `error_description` | `error_details`[] |
337261
| -------------------- | ------------------------------------------------- | ------------------------------- |
338-
| `bad_param` | A validation error occurred. | Array of parameters with errors |
339-
| `missing_param` | A required parameter is missing. | Array of missing parameters |
262+
| `bad_param` | A validation error occurred | Array of parameters with errors |
263+
| `missing_param` | A required parameter is missing | Array of missing parameters |
264+
| `unregistered` | This `device_id` is unregistered | |
265+
340266

341267
[Top][toc]
342268

343269
[accessibility-options]: /general-information.md#accessibility-options
344270
[beta]: /general-information.md#beta-features
271+
[bulk-responses]: /general-information.md#bulk-responses
345272
[general]: /general-information.md
346273
[geography-driven-events]: /general-information.md#geography-driven-events
347274
[error-messages]: /general-information.md#error-messages

0 commit comments

Comments
 (0)