Booking API (originally by MaaS Global) #10
Conversation
Co-authored-by: laurisvan Co-authored-by: Feijk
brylie
changed the title
booking.yaml
Outdated
| openapi: 3.0.0 | ||
| servers: [] | ||
| info: | ||
| version: 0.1 |
There was a problem hiding this comment.
Should be version: 0.1.0, otherwise http://editor.swagger.io complains with an error.
booking.yaml
Outdated
| description: > | ||
| This is a API specification of REST endpoints that a Transport Service | ||
| Provider (TSP) should implement to receive messages from MaaS Operator(s). It is written | ||
| in machine readable [Swagger](http://swagger.io/) format, so that API |
There was a problem hiding this comment.
The Sagger format has since been renamed "OpenAPI Spec"
booking.yaml
Outdated
| TSP. | ||
| externalDocs: | ||
| description: Booking scenarios | ||
| url: 'https://github.com/maasglobal/maas-tsp-api/blob/master/specs/Booking.md' |
There was a problem hiding this comment.
Should this also be added to this repo?
booking.yaml
Outdated
| - name: Listing | ||
| description: >- | ||
| Before a booking can be made via a TSP, available options at a given | ||
| location can be listed as follows |
There was a problem hiding this comment.
How about naming this a "Quote" instead? "Listing" is more general and less descriptive, but I think this is essentially for getting a quote which can later be booked?
booking.yaml
Outdated
| description: >- | ||
| In the future MaaS will implement machine-readable APIs that a TSP may use | ||
| to update GTFS route information, API keys and other information that is | ||
| needed for communicating between MaaS and a TSP. |
There was a problem hiding this comment.
I'd leave those TODO tags out of this PR and create separate issues for them.
| - startTime | ||
| - endTime | ||
| place: | ||
| type: object |
There was a problem hiding this comment.
Can reuse Location and StopLocation
There was a problem hiding this comment.
Cool. How should we separate those definitions, so they can be shared between APIs?
There was a problem hiding this comment.
Enhancement opened:
#11
booking.yaml
Outdated
| time: | ||
| description: >- | ||
| A UTC timestamp (number of milliseconds in a Date object since January | ||
| 1, 1970, 00:00:00) |
There was a problem hiding this comment.
We see more APIs switch to ISO8601 for times as it makes developing and making sense of looking at API responses much simpler, so I suggest to switch to that.
There was a problem hiding this comment.
Agreed, ISO8601 is good. Not sure why epoch was chosen, but we seem to have it in a lot of places internally, including object sub-fields (JSONB). This adds a bit of difficulty when working with the data.
booking.yaml
Outdated
| A UTC timestamp (number of milliseconds in a Date object since January | ||
| 1, 1970, 00:00:00) | ||
| duration: | ||
| description: A duration of some time (relative to time) in milliseconds |
There was a problem hiding this comment.
Milliseconds seems unnecessary high precision, would recommend seconds.
There was a problem hiding this comment.
Jep, milliseconds is a bit difficult to work with. I am not sure why it was in the original spec.
| minimum: 0 | ||
| fare: | ||
| description: Arbitrary fare data that MaaS will use internally | ||
| type: object |
There was a problem hiding this comment.
Would be good to have a schema or recommendation in place for this.
There was a problem hiding this comment.
Cool. Can we open an enhancement issue for the fare schema?
There was a problem hiding this comment.
Yes, let's make this an enhancement issue.
There was a problem hiding this comment.
Enhancement issue created
#13
| description: Arbitrary fare data that MaaS will use internally | ||
| type: object | ||
| mode: | ||
| description: The type of the leg MaaS uses to identify the leg |
There was a problem hiding this comment.
Can reuse ModeInfo and particularly the "mode identifiers" to have a defined hierarchy of supported modes and make it consistent across APIs.
There was a problem hiding this comment.
How can we split these out, so they can be shared between APIs?
There was a problem hiding this comment.
Let's make this an enhancement issue.
Co-authored-by: Tomi Niittumäki [email protected] Co-authored-by: Lauri Svan [email protected]
Co-authored-by: Lauri Svan [email protected]
|
@nighthawk, I have made agreed changes and opened related enhancement issues #11 and #13. Please review. |
Booking API that can be used by Transportation Service Providers to allow MaaS Operators to make bookings in a given transportation service network.