openmobilityfoundation / mds-openapi Goto Github PK

View Code? Open in Web Editor NEW

8.0 2.0 2.0 294 KB

OpenAPI description for MDS data feeds, managed by the Open Mobility Foundation.

Home Page: https://openmobilityfnd.stoplight.io/docs/mds-openapi

License: Other

Jupyter Notebook 42.70% Python 57.30%

openapi3 openapi bike-share cities mds mobility mobility-as-a-service policy delivery-robot micromobility

mds-openapi's People

Contributors

Stargazers

Watchers

Forkers

compilerla mihailpw

mds-openapi's Issues

Describe 400 for Provider endpoints with params

All Provider endpoints that accept parameters (either in the path or in query string) should define a 400 response code.

Fix mode trip_id requirements and event_types

RE: openmobilityfoundation/mobility-data-specification#843 (comment)

`car-share`

trip_end
trip_resume
trip_start
trip_stop

`delivery-robots`

trip_end
trip_resume
trip_start
trip_pause

`micromobility`

trip_cancel
trip_end
trip_start

`passenger-services`

trip_end
trip_resume
trip_start
trip_stop

vehicle_type allowed values

Currently, vehicle_type is described here and shared between all the modes.
My question is should it be one list of allowed values for all modes? I assume allowed values should be separated per each mode.

Seems like it should be separated to each mode, like:

bicycle is related to micromobility
bus - passenger-services (?)
cargo_bicycle - micromobility
car - car-share
delivery_robot - delivery-robots
moped - micromobility
motorcycle - micromobility (?)
scooter_standing - micromobility
scooter_seated - micromobility
truck - car-share
other - ...

Could you please review this moment?

Conflict in documentation regarding Trip - trip_type

So is trip_type one string or many strings in array ?

https://github.com/openmobilityfoundation/mobility-data-specification/blob/2.0.0/data-types.md#trips

https://github.com/openmobilityfoundation/mobility-data-specification/blob/2.0.0/modes/micromobility.md#trip-type

https://openmobilityfnd.stoplight.io/docs/mds-openapi/0f4cefcc4c183-trips

Metrics API

Spec description: https://github.com/openmobilityfoundation/mobility-data-specification/tree/release-2.0.0/metrics

Endpoints

/metrics: GET
/metrics: POST

Data requirements

ISO 8601 formatted strings with minute granularity supported and time zone (default UTC - YYYY-MM-DDTHH:mm or included offset (YYYY-MM-DDTHH:mm). Dates and times may also be specified using a numeric Unix epoch/timestamp
ISO 8601 duration format strings (e.g. PT15M, PT1H, P1D)
metrics GET response
metrics POST parameters
metrics POST response

Agency API

Spec description: https://github.com/openmobilityfoundation/mobility-data-specification/tree/release-2.0.0/agency

Endpoints

Data requirements

Is it possible to create somehow one OpenApi file?

I'm used to generate code using the swagger editor (https://editor.swagger.io/). Therefore the code should be in one file. Is it possible to obtain all the parts in one file?

Geography API

Spec description: https://github.com/openmobilityfoundation/mobility-data-specification/tree/release-2.0.0/geography

Endpoints

/geographies: GET
/geographies.json: GET
/geographies/{geography_id}: GET

Data requirements

geography
geography.geography_json: GeoJSON FeatureCollection reference
geography_type - this isn't actually an enum, but a list of recommended strings (implemented as examples)

Media type in OpenAPI

UPDATE

See comment below #34 (comment)

Original

MDS defines the media type application/vnd.mds+json for use in the (response) Content-type header, and for the purposes of version negotiation whereby a client could request a particular version:

Accept application/vnd.mds+json;version=2.0

The OpenAPI endpoints thus far have used application/vnd.mds+json as the Content-type and not required it as an Accept header.

Use endpoint for summary field

E.g. in the Provider API doc we have:

/vehicles:
    get:
      operationId: get-vehicles
      description: Get a list of known vehicles, with properties that do not change often.
      summary: Get near-realtime vehicle information.

In the Stoplight menu, this looks like (notice some items are cut off):

Instead reuse the endpoint name in the summary field:

/vehicles:
    get:
      operationId: get-vehicles
      description: Get a list of known vehicles, with properties that do not change often.
      summary: /vehicles

This will reduce duplication within these OpenAPI docs and with the MDS docs, and it makes it much clearer in the Stoplight menu:

Add securitySchemes for Metrics

https://github.com/openmobilityfoundation/mobility-data-specification/blob/release-2.0.0/metrics/README.md#authorization

Agency GET endpoints return MDS version in responses

Agency GET endpoints return their data payload, and optionally the JSON API pagination fields, e.g. for Vehicles:

{
    "vehicles": [ ... ],
    "links": {
        "first": "https://...",
        "last": "https://...",
        "prev": "https://...",
        "next": "https://..."
    }
}

Should the MDS version be included in this response? Like it is for Provider, Policy, Jurisdiction responses?

{
    "version": "2.0.0",
    "vehicles": [ ... ],
    "links": {
        "first": "https://...",
        "last": "https://...",
        "prev": "https://...",
        "next": "https://..."
    }
}