From 59d2da930331ba2a39934a359706aaabe4daf22d Mon Sep 17 00:00:00 2001 From: gkoberger Date: Fri, 15 Mar 2024 13:48:37 -0400 Subject: [PATCH 1/2] train --- 3.1/json/train-travel.json | 1657 ++++++++++++++++++++++++++++++++++++ 3.1/yaml/train-travel.yaml | 1099 ++++++++++++++++++++++++ 2 files changed, 2756 insertions(+) create mode 100644 3.1/json/train-travel.json create mode 100644 3.1/yaml/train-travel.yaml diff --git a/3.1/json/train-travel.json b/3.1/json/train-travel.json new file mode 100644 index 0000000..997d0b8 --- /dev/null +++ b/3.1/json/train-travel.json @@ -0,0 +1,1657 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Train Travel API", + "description": "API for finding and booking train trips across Europe.", + "version": "1.0.0", + "contact": { + "name": "Train Support", + "url": "https://example.com/support", + "email": "support@example.com" + }, + "license": { + "name": "Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International", + "identifier": "CC-BY-NC-SA-4.0" + } + }, + "x-topics": [ + { + "title": "Getting started", + "content": { + "$ref": "./docs/getting-started.md" + } + } + ], + "servers": [ + { + "url": "https://api.example.com", + "description": "Production" + } + ], + "security": [ + { + "OAuth2": [ + "read" + ] + } + ], + "tags": [ + { + "name": "Stations", + "description": "Find and filter train stations across Europe, including their location and local timezone." + }, + { + "name": "Trips", + "description": "Timetables and routes for train trips between stations, including pricing and availability." + }, + { + "name": "Bookings", + "description": "Create and manage bookings for train trips, including passenger details and optional extras." + }, + { + "name": "Payments", + "description": "Pay for bookings using a card or bank account, and view payment\nstatus and history.\n\n> warn\n> Bookings usually expire within 1 hour so you'll need to make your payment before the expiry date \n" + } + ], + "paths": { + "/stations": { + "get": { + "summary": "Get a list of train stations", + "description": "Returns a list of all train stations in the system.", + "operationId": "get-stations", + "tags": [ + "Stations" + ], + "responses": { + "200": { + "description": "A list of train stations", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + }, + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Wrapper-Collection" + }, + { + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Station" + } + } + } + }, + { + "properties": { + "links": { + "allOf": [ + { + "$ref": "#/components/schemas/Links-Self" + }, + { + "$ref": "#/components/schemas/Links-Pagination" + } + ] + } + } + } + ] + }, + "example": { + "data": [ + { + "id": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "name": "Berlin Hauptbahnhof", + "address": "Invalidenstraße 10557 Berlin, Germany", + "country_code": "DE", + "timezone": "Europe/Berlin" + }, + { + "id": "b2e783e1-c824-4d63-b37a-d8d698862f1d", + "name": "Paris Gare du Nord", + "address": "18 Rue de Dunkerque 75010 Paris, France", + "country_code": "FR", + "timezone": "Europe/Paris" + } + ], + "links": { + "self": "https://api.example.com/stations&page=2", + "next": "https://api.example.com/stations?page=3", + "prev": "https://api.example.com/stations?page=1" + } + } + }, + "application/xml": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Wrapper-Collection" + }, + { + "properties": { + "data": { + "type": "array", + "xml": { + "name": "stations", + "wrapped": true + }, + "items": { + "$ref": "#/components/schemas/Station" + } + } + } + }, + { + "properties": { + "links": { + "allOf": [ + { + "$ref": "#/components/schemas/Links-Self" + }, + { + "$ref": "#/components/schemas/Links-Pagination" + } + ] + } + } + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/trips": { + "get": { + "summary": "Get available train trips", + "description": "Returns a list of available train trips between the specified origin and destination stations on the given date, and allows for filtering by bicycle and dog allowances.", + "operationId": "get-trips", + "tags": [ + "Trips" + ], + "parameters": [ + { + "name": "origin", + "in": "query", + "description": "The ID of the origin station", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e" + }, + { + "name": "destination", + "in": "query", + "description": "The ID of the destination station", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "b2e783e1-c824-4d63-b37a-d8d698862f1d" + }, + { + "name": "date", + "in": "query", + "description": "The date and time of the trip in ISO 8601 format in origin station's timezone.", + "required": true, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2024-02-01T09:00:00Z" + }, + { + "name": "bicycles", + "in": "query", + "description": "Only return trips where bicycles are known to be allowed", + "required": false, + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "dogs", + "in": "query", + "description": "Only return trips where dogs are known to be allowed", + "required": false, + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "A list of available train trips", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + }, + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Wrapper-Collection" + }, + { + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Trip" + } + } + } + }, + { + "properties": { + "links": { + "allOf": [ + { + "$ref": "#/components/schemas/Links-Self" + }, + { + "$ref": "#/components/schemas/Links-Pagination" + } + ] + } + } + } + ] + }, + "example": { + "data": [ + { + "id": "ea399ba1-6d95-433f-92d1-83f67b775594", + "origin": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "destination": "b2e783e1-c824-4d63-b37a-d8d698862f1d", + "departure_time": "2024-02-01T10:00:00Z", + "arrival_time": "2024-02-01T16:00:00Z", + "price": 50, + "operator": "Deutsche Bahn", + "bicycles_allowed": true, + "dogs_allowed": true + }, + { + "id": "4d67459c-af07-40bb-bb12-178dbb88e09f", + "origin": "b2e783e1-c824-4d63-b37a-d8d698862f1d", + "destination": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "departure_time": "2024-02-01T12:00:00Z", + "arrival_time": "2024-02-01T18:00:00Z", + "price": 50, + "operator": "SNCF", + "bicycles_allowed": true, + "dogs_allowed": true + } + ], + "links": { + "self": "https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=b2e783e1-c824-4d63-b37a-d8d698862f1d&date=2024-02-01", + "next": "https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=b2e783e1-c824-4d63-b37a-d8d698862f1d&date=2024-02-01&page=2" + } + } + }, + "application/xml": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Wrapper-Collection" + }, + { + "properties": { + "data": { + "type": "array", + "xml": { + "name": "trips", + "wrapped": true + }, + "items": { + "$ref": "#/components/schemas/Trip" + } + } + } + }, + { + "properties": { + "links": { + "allOf": [ + { + "$ref": "#/components/schemas/Links-Self" + }, + { + "$ref": "#/components/schemas/Links-Pagination" + } + ] + } + } + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/bookings": { + "get": { + "operationId": "get-bookings", + "summary": "List existing bookings", + "description": "Returns a list of all trips booking by the authenticated user.", + "tags": [ + "Bookings" + ], + "responses": { + "200": { + "description": "A list of bookings", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + }, + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Wrapper-Collection" + }, + { + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Booking" + } + } + } + }, + { + "properties": { + "links": { + "allOf": [ + { + "$ref": "#/components/schemas/Links-Self" + }, + { + "$ref": "#/components/schemas/Links-Pagination" + } + ] + } + } + } + ] + }, + "example": { + "data": [ + { + "id": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "trip_id": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "passenger_name": "John Doe", + "has_bicycle": true, + "has_dog": true + }, + { + "id": "b2e783e1-c824-4d63-b37a-d8d698862f1d", + "trip_id": "b2e783e1-c824-4d63-b37a-d8d698862f1d", + "passenger_name": "Jane Smith", + "has_bicycle": false, + "has_dog": false + } + ], + "links": { + "self": "https://api.example.com/bookings", + "next": "https://api.example.com/bookings?page=2" + } + } + }, + "application/xml": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Wrapper-Collection" + }, + { + "properties": { + "data": { + "type": "array", + "xml": { + "name": "bookings", + "wrapped": true + }, + "items": { + "$ref": "#/components/schemas/Booking" + } + } + } + }, + { + "properties": { + "links": { + "allOf": [ + { + "$ref": "#/components/schemas/Links-Self" + }, + { + "$ref": "#/components/schemas/Links-Pagination" + } + ] + } + } + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + }, + "post": { + "operationId": "create-booking", + "summary": "Create a booking", + "description": "A booking is a temporary hold on a trip. It is not confirmed until the payment is processed.", + "tags": [ + "Bookings" + ], + "security": [ + { + "OAuth2": [ + "write" + ] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Booking" + } + }, + "application/xml": { + "schema": { + "$ref": "#/components/schemas/Booking" + } + } + } + }, + "responses": { + "201": { + "description": "Booking successful", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Booking" + }, + { + "properties": { + "links": { + "$ref": "#/components/schemas/Links-Self" + } + } + } + ] + }, + "example": { + "id": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "trip_id": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "passenger_name": "John Doe", + "has_bicycle": true, + "has_dog": true, + "links": { + "self": "https://api.example.com/bookings/efdbb9d1-02c2-4bc3-afb7-6788d8782b1e" + } + } + }, + "application/xml": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Booking" + }, + { + "properties": { + "links": { + "$ref": "#/components/schemas/Links-Self" + } + } + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "409": { + "$ref": "#/components/responses/Conflict" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/bookings/{bookingId}": { + "parameters": [ + { + "name": "bookingId", + "in": "path", + "required": true, + "description": "The ID of the booking to retrieve.", + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "1725ff48-ab45-4bb5-9d02-88745177dedb" + } + ], + "get": { + "summary": "Get a booking", + "description": "Returns the details of a specific booking.", + "operationId": "get-booking", + "tags": [ + "Bookings" + ], + "responses": { + "200": { + "description": "The booking details", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + }, + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Booking" + }, + { + "properties": { + "links": { + "$ref": "#/components/schemas/Links-Self" + } + } + } + ] + }, + "example": { + "id": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "trip_id": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "passenger_name": "John Doe", + "has_bicycle": true, + "has_dog": true, + "links": { + "self": "https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb" + } + } + }, + "application/xml": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Booking" + }, + { + "properties": { + "links": { + "$ref": "#/components/schemas/Links-Self" + } + } + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + }, + "delete": { + "summary": "Delete a booking", + "description": "Deletes a booking, cancelling the hold on the trip.", + "operationId": "delete-booking", + "security": [ + { + "OAuth2": [ + "write" + ] + } + ], + "tags": [ + "Bookings" + ], + "responses": { + "204": { + "description": "Booking deleted" + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/bookings/{bookingId}/payment": { + "parameters": [ + { + "name": "bookingId", + "in": "path", + "required": true, + "description": "The ID of the booking to pay for.", + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "1725ff48-ab45-4bb5-9d02-88745177dedb" + } + ], + "post": { + "summary": "Pay for a Booking", + "description": "A payment is an attempt to pay for the booking, which will confirm the booking for the user and enable them to get their tickets.", + "operationId": "create-booking-payment", + "tags": [ + "Payments" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BookingPayment" + }, + "examples": { + "Card": { + "summary": "Card Payment", + "value": { + "amount": 49.99, + "currency": "gbp", + "source": { + "object": "card", + "name": "J. Doe", + "number": "4242424242424242", + "cvc": 123, + "exp_month": 12, + "exp_year": 2025, + "address_line1": "123 Fake Street", + "address_line2": "4th Floor", + "address_city": "London", + "address_country": "gb", + "address_post_code": "N12 9XX" + } + } + }, + "Bank": { + "summary": "Bank Account Payment", + "value": { + "amount": 100.5, + "currency": "gbp", + "source": { + "object": "bank_account", + "name": "J. Doe", + "number": "00012345", + "sort_code": "000123", + "account_type": "individual", + "bank_name": "Starling Bank", + "country": "gb" + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Payment successful", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + }, + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/BookingPayment" + }, + { + "properties": { + "links": { + "$ref": "#/components/schemas/Links-Booking" + } + } + } + ] + }, + "examples": { + "Card": { + "summary": "Card Payment", + "value": { + "id": "2e3b4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a", + "amount": 49.99, + "currency": "gbp", + "source": { + "object": "card", + "name": "J. Doe", + "number": "************4242", + "cvc": 123, + "exp_month": 12, + "exp_year": 2025, + "address_country": "gb", + "address_post_code": "N12 9XX" + }, + "status": "succeeded", + "links": { + "booking": "https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb/payment" + } + } + }, + "Bank": { + "summary": "Bank Account Payment", + "value": { + "id": "2e3b4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a", + "amount": 100.5, + "currency": "gbp", + "source": { + "object": "bank_account", + "name": "J. Doe", + "account_type": "individual", + "number": "*********2345", + "sort_code": "000123", + "bank_name": "Starling Bank", + "country": "gb" + }, + "status": "succeeded", + "links": { + "booking": "https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + } + }, + "webhooks": { + "newBooking": { + "post": { + "operationId": "new-booking", + "summary": "New Booking", + "description": "Subscribe to new bookings being created, to update integrations for your users. Related data is available via the links provided in the request.\n", + "tags": [ + "Bookings" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Booking" + }, + { + "properties": { + "links": { + "allOf": [ + { + "$ref": "#/components/schemas/Links-Self" + }, + { + "$ref": "#/components/schemas/Links-Pagination" + } + ] + } + } + } + ] + }, + "example": { + "id": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "trip_id": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "passenger_name": "John Doe", + "has_bicycle": true, + "has_dog": true, + "links": { + "self": "https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb" + } + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status to indicate that the data was received successfully.", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "OAuth2": { + "type": "oauth2", + "description": "OAuth 2.0 authorization code following RFC8725 best practices.", + "flows": { + "authorizationCode": { + "authorizationUrl": "https://example.com/oauth/authorize", + "tokenUrl": "https://example.com/oauth/token", + "scopes": { + "read": "Read access", + "write": "Write access" + } + } + } + } + }, + "schemas": { + "Station": { + "type": "object", + "xml": { + "name": "station" + }, + "required": [ + "id", + "name", + "address", + "country_code" + ], + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique identifier for the station.", + "examples": [ + "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e", + "b2e783e1-c824-4d63-b37a-d8d698862f1d" + ] + }, + "name": { + "type": "string", + "description": "The name of the station", + "examples": [ + "Berlin Hauptbahnhof", + "Paris Gare du Nord" + ] + }, + "address": { + "type": "string", + "description": "The address of the station.", + "examples": [ + "Invalidenstraße 10557 Berlin, Germany", + "18 Rue de Dunkerque 75010 Paris, France" + ] + }, + "country_code": { + "type": "string", + "description": "The country code of the station.", + "format": "iso-country-code", + "examples": [ + "DE", + "FR" + ] + }, + "timezone": { + "type": "string", + "description": "The timezone of the station in the [IANA Time Zone Database format](https://www.iana.org/time-zones).", + "examples": [ + "Europe/Berlin", + "Europe/Paris" + ] + } + } + }, + "Links-Self": { + "type": "object", + "properties": { + "self": { + "type": "string", + "format": "uri" + } + } + }, + "Links-Pagination": { + "type": "object", + "properties": { + "next": { + "type": "string", + "format": "uri" + }, + "prev": { + "type": "string", + "format": "uri" + } + } + }, + "Problem": { + "xml": { + "name": "problem", + "namespace": "urn:ietf:rfc:7807" + }, + "properties": { + "type": { + "type": "string", + "description": "A URI reference that identifies the problem type", + "example": "https://example.com/probs/out-of-credit" + }, + "title": { + "type": "string", + "description": "A short, human-readable summary of the problem type", + "example": "You do not have enough credit." + }, + "detail": { + "type": "string", + "description": "A human-readable explanation specific to this occurrence of the problem", + "example": "Your current balance is 30, but that costs 50." + }, + "instance": { + "type": "string", + "description": "A URI reference that identifies the specific occurrence of the problem", + "example": "/account/12345/msgs/abc" + }, + "status": { + "type": "integer", + "description": "The HTTP status code", + "example": 400 + } + } + }, + "Trip": { + "type": "object", + "xml": { + "name": "trip" + }, + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique identifier for the trip", + "examples": [ + "4f4e4e1-c824-4d63-b37a-d8d698862f1d" + ] + }, + "origin": { + "type": "string", + "description": "The starting station of the trip", + "examples": [ + "Berlin Hauptbahnhof", + "Paris Gare du Nord" + ] + }, + "destination": { + "type": "string", + "description": "The destination station of the trip", + "examples": [ + "Paris Gare du Nord", + "Berlin Hauptbahnhof" + ] + }, + "departure_time": { + "type": "string", + "format": "date-time", + "description": "The date and time when the trip departs", + "examples": [ + "2024-02-01T10:00:00Z" + ] + }, + "arrival_time": { + "type": "string", + "format": "date-time", + "description": "The date and time when the trip arrives", + "examples": [ + "2024-02-01T16:00:00Z" + ] + }, + "operator": { + "type": "string", + "description": "The name of the operator of the trip", + "examples": [ + "Deutsche Bahn", + "SNCF" + ] + }, + "price": { + "type": "number", + "description": "The cost of the trip", + "examples": [ + 50 + ] + }, + "bicycles_allowed": { + "type": "boolean", + "description": "Indicates whether bicycles are allowed on the trip" + }, + "dogs_allowed": { + "type": "boolean", + "description": "Indicates whether dogs are allowed on the trip" + } + } + }, + "Booking": { + "type": "object", + "xml": { + "name": "booking" + }, + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique identifier for the booking", + "readOnly": true, + "examples": [ + "3f3e3e1-c824-4d63-b37a-d8d698862f1d" + ] + }, + "trip_id": { + "type": "string", + "format": "uuid", + "description": "Identifier of the booked trip", + "examples": [ + "4f4e4e1-c824-4d63-b37a-d8d698862f1d" + ] + }, + "passenger_name": { + "type": "string", + "description": "Name of the passenger", + "examples": [ + "John Doe" + ] + }, + "has_bicycle": { + "type": "boolean", + "description": "Indicates whether the passenger has a bicycle." + }, + "has_dog": { + "type": "boolean", + "description": "Indicates whether the passenger has a dog." + } + } + }, + "Wrapper-Collection": { + "description": "This is a generic request/response wrapper which contains both data and links which serve as hypermedia controls (HATEOAS).", + "type": "object", + "properties": { + "data": { + "description": "The wrapper for a collection is an array of objects.", + "type": "array", + "items": { + "type": "object" + } + }, + "links": { + "description": "A set of hypermedia links which serve as controls for the client.", + "type": "object", + "readOnly": true + } + }, + "xml": { + "name": "data" + } + }, + "BookingPayment": { + "type": "object", + "properties": { + "id": { + "description": "Unique identifier for the payment. This will be a unique identifier for the payment, and is used to reference the payment in other objects.", + "type": "string", + "format": "uuid", + "readOnly": true + }, + "amount": { + "description": "Amount intended to be collected by this payment. A positive decimal figure describing the amount to be collected.", + "type": "number", + "exclusiveMinimum": 0, + "examples": [ + 49.99 + ] + }, + "currency": { + "description": "Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.", + "type": "string", + "enum": [ + "bam", + "bgn", + "chf", + "eur", + "gbp", + "nok", + "sek", + "try" + ] + }, + "source": { + "unevaluatedProperties": false, + "description": "The payment source to take the payment from. This can be a card or a bank account. Some of these properties will be hidden on read to protect PII leaking.", + "anyOf": [ + { + "title": "Card", + "description": "A card (debit or credit) to take payment from.", + "properties": { + "object": { + "type": "string", + "const": "card" + }, + "name": { + "type": "string", + "description": "Cardholder's full name as it appears on the card.", + "examples": [ + "Francis Bourgeois" + ] + }, + "number": { + "type": "string", + "description": "The card number, as a string without any separators. On read all but the last four digits will be masked for security.", + "examples": [ + "4242424242424242" + ] + }, + "cvc": { + "type": "integer", + "description": "Card security code, 3 or 4 digits usually found on the back of the card.", + "minLength": 3, + "maxLength": 4, + "writeOnly": true, + "example": 123 + }, + "exp_month": { + "type": "integer", + "format": "int64", + "description": "Two-digit number representing the card's expiration month.", + "examples": [ + 12 + ] + }, + "exp_year": { + "type": "integer", + "format": "int64", + "description": "Four-digit number representing the card's expiration year.", + "examples": [ + 2025 + ] + }, + "address_line1": { + "type": "string", + "writeOnly": true + }, + "address_line2": { + "type": "string", + "writeOnly": true + }, + "address_city": { + "type": "string" + }, + "address_country": { + "type": "string" + }, + "address_post_code": { + "type": "string" + } + }, + "required": [ + "name", + "number", + "cvc", + "exp_month", + "exp_year", + "address_country" + ] + }, + { + "title": "Bank Account", + "description": "A bank account to take payment from. Must be able to make payments in the currency specified in the payment.", + "type": "object", + "properties": { + "object": { + "const": "bank_account", + "type": "string" + }, + "name": { + "type": "string" + }, + "number": { + "type": "string", + "description": "The account number for the bank account, in string form. Must be a current account." + }, + "sort_code": { + "type": "string", + "description": "The sort code for the bank account, in string form. Must be a six-digit number." + }, + "account_type": { + "enum": [ + "individual", + "company" + ], + "type": "string", + "description": "The type of entity that holds the account. This can be either `individual` or `company`." + }, + "bank_name": { + "type": "string", + "description": "The name of the bank associated with the routing number.", + "examples": [ + "Starling Bank" + ] + }, + "country": { + "type": "string", + "description": "Two-letter country code (ISO 3166-1 alpha-2)." + } + }, + "required": [ + "name", + "number", + "account_type", + "bank_name", + "country" + ] + } + ] + }, + "status": { + "description": "The status of the payment, one of `pending`, `succeeded`, or `failed`.", + "type": "string", + "enum": [ + "pending", + "succeeded", + "failed" + ], + "readOnly": true + } + } + }, + "Links-Booking": { + "type": "object", + "properties": { + "booking": { + "type": "string", + "format": "uri", + "examples": [ + "https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb" + ] + } + } + } + }, + "headers": { + "RateLimit": { + "description": "The RateLimit header is communicate quota policies, and contains a `limit` to\nconveys the expiring limit, `remaining` to convey the remaining quota units,\nand `reset` to convey the time window reset time.\n", + "schema": { + "type": "string", + "examples": [ + "limit=10, remaining=0, reset=10" + ] + } + }, + "Retry-After": { + "description": "The Retry-After header indicates how long the user agent should wait before making a follow-up request. \nThe value is in seconds and can be an integer or a date in the future. \nIf the value is an integer, it indicates the number of seconds to wait. \nIf the value is a date, it indicates the time at which the user agent should make a follow-up request. \n", + "schema": { + "type": "string" + }, + "examples": { + "integer": { + "value": "120", + "summary": "Retry after 120 seconds" + }, + "date": { + "value": "Fri, 31 Dec 2021 23:59:59 GMT", + "summary": "Retry after the specified date" + } + } + } + }, + "responses": { + "BadRequest": { + "description": "Bad Request", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + }, + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/bad-request", + "title": "Bad Request", + "status": 400, + "detail": "The request is invalid or missing required parameters." + } + }, + "application/problem+xml": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/bad-request", + "title": "Bad Request", + "status": 400, + "detail": "The request is invalid or missing required parameters." + } + } + } + }, + "Conflict": { + "description": "Conflict", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + }, + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/conflict", + "title": "Conflict", + "status": 409, + "detail": "There is a conflict with an existing resource." + } + }, + "application/problem+xml": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/conflict", + "title": "Conflict", + "status": 409, + "detail": "There is a conflict with an existing resource." + } + } + } + }, + "Forbidden": { + "description": "Forbidden", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + }, + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/forbidden", + "title": "Forbidden", + "status": 403, + "detail": "Access is forbidden for the provided credentials." + } + }, + "application/problem+xml": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/forbidden", + "title": "Forbidden", + "status": 403, + "detail": "Access is forbidden for the provided credentials." + } + } + } + }, + "InternalServerError": { + "description": "Internal Server Error", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + }, + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/internal-server-error", + "title": "Internal Server Error", + "status": 500, + "detail": "An unexpected error occurred." + } + }, + "application/problem+xml": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/internal-server-error", + "title": "Internal Server Error", + "status": 500, + "detail": "An unexpected error occurred." + } + } + } + }, + "NotFound": { + "description": "Not Found", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + }, + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/not-found", + "title": "Not Found", + "status": 404, + "detail": "The requested resource was not found." + } + }, + "application/problem+xml": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/not-found", + "title": "Not Found", + "status": 404, + "detail": "The requested resource was not found." + } + } + } + }, + "TooManyRequests": { + "description": "Too Many Requests", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "Retry-After": { + "$ref": "#/components/headers/Retry-After" + } + }, + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/too-many-requests", + "title": "Too Many Requests", + "status": 429, + "detail": "You have exceeded the rate limit." + } + }, + "application/problem+xml": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/too-many-requests", + "title": "Too Many Requests", + "status": 429, + "detail": "You have exceeded the rate limit." + } + } + } + }, + "Unauthorized": { + "description": "Unauthorized", + "headers": { + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + } + }, + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/unauthorized", + "title": "Unauthorized", + "status": 401, + "detail": "You do not have the necessary permissions." + } + }, + "application/problem+xml": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://example.com/errors/unauthorized", + "title": "Unauthorized", + "status": 401, + "detail": "You do not have the necessary permissions." + } + } + } + } + } + } +} diff --git a/3.1/yaml/train-travel.yaml b/3.1/yaml/train-travel.yaml new file mode 100644 index 0000000..04804a1 --- /dev/null +++ b/3.1/yaml/train-travel.yaml @@ -0,0 +1,1099 @@ +openapi: 3.1.0 +info: + title: Train Travel API + description: API for finding and booking train trips across Europe. + version: 1.0.0 + contact: + name: Train Support + url: https://example.com/support + email: support@example.com + license: + name: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International + identifier: CC-BY-NC-SA-4.0 + +x-topics: + - title: Getting started + content: + $ref: ./docs/getting-started.md +servers: + - url: https://api.example.com + description: Production +security: + - OAuth2: + - read +tags: + - name: Stations + description: Find and filter train stations across Europe, including their location and local timezone. + - name: Trips + description: Timetables and routes for train trips between stations, including pricing and availability. + - name: Bookings + description: Create and manage bookings for train trips, including passenger details and optional extras. + - name: Payments + description: | + Pay for bookings using a card or bank account, and view payment + status and history. + + > warn + > Bookings usually expire within 1 hour so you'll need to make your payment before the expiry date +paths: + /stations: + get: + summary: Get a list of train stations + description: Returns a list of all train stations in the system. + operationId: get-stations + tags: + - Stations + responses: + '200': + description: A list of train stations + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Wrapper-Collection' + - properties: + data: + type: array + items: + $ref: '#/components/schemas/Station' + - properties: + links: + allOf: + - $ref: '#/components/schemas/Links-Self' + - $ref: '#/components/schemas/Links-Pagination' + example: + data: + - id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + name: Berlin Hauptbahnhof + address: Invalidenstraße 10557 Berlin, Germany + country_code: DE + timezone: Europe/Berlin + - id: b2e783e1-c824-4d63-b37a-d8d698862f1d + name: Paris Gare du Nord + address: 18 Rue de Dunkerque 75010 Paris, France + country_code: FR + timezone: Europe/Paris + links: + self: https://api.example.com/stations&page=2 + next: https://api.example.com/stations?page=3 + prev: https://api.example.com/stations?page=1 + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/Wrapper-Collection' + - properties: + data: + type: array + xml: + name: stations + wrapped: true + items: + $ref: '#/components/schemas/Station' + - properties: + links: + allOf: + - $ref: '#/components/schemas/Links-Self' + - $ref: '#/components/schemas/Links-Pagination' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + $ref: '#/components/responses/InternalServerError' + /trips: + get: + summary: Get available train trips + description: Returns a list of available train trips between the specified origin and destination stations on the given date, and allows for filtering by bicycle and dog allowances. + operationId: get-trips + tags: + - Trips + parameters: + - name: origin + in: query + description: The ID of the origin station + required: true + schema: + type: string + format: uuid + example: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + - name: destination + in: query + description: The ID of the destination station + required: true + schema: + type: string + format: uuid + example: b2e783e1-c824-4d63-b37a-d8d698862f1d + - name: date + in: query + description: The date and time of the trip in ISO 8601 format in origin station's timezone. + required: true + schema: + type: string + format: date-time + example: '2024-02-01T09:00:00Z' + - name: bicycles + in: query + description: Only return trips where bicycles are known to be allowed + required: false + schema: + type: boolean + default: false + - name: dogs + in: query + description: Only return trips where dogs are known to be allowed + required: false + schema: + type: boolean + default: false + responses: + '200': + description: A list of available train trips + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Wrapper-Collection' + - properties: + data: + type: array + items: + $ref: '#/components/schemas/Trip' + - properties: + links: + allOf: + - $ref: '#/components/schemas/Links-Self' + - $ref: '#/components/schemas/Links-Pagination' + example: + data: + - id: ea399ba1-6d95-433f-92d1-83f67b775594 + origin: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + destination: b2e783e1-c824-4d63-b37a-d8d698862f1d + departure_time: '2024-02-01T10:00:00Z' + arrival_time: '2024-02-01T16:00:00Z' + price: 50 + operator: Deutsche Bahn + bicycles_allowed: true + dogs_allowed: true + - id: 4d67459c-af07-40bb-bb12-178dbb88e09f + origin: b2e783e1-c824-4d63-b37a-d8d698862f1d + destination: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + departure_time: '2024-02-01T12:00:00Z' + arrival_time: '2024-02-01T18:00:00Z' + price: 50 + operator: SNCF + bicycles_allowed: true + dogs_allowed: true + links: + self: https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=b2e783e1-c824-4d63-b37a-d8d698862f1d&date=2024-02-01 + next: https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=b2e783e1-c824-4d63-b37a-d8d698862f1d&date=2024-02-01&page=2 + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/Wrapper-Collection' + - properties: + data: + type: array + xml: + name: trips + wrapped: true + items: + $ref: '#/components/schemas/Trip' + - properties: + links: + allOf: + - $ref: '#/components/schemas/Links-Self' + - $ref: '#/components/schemas/Links-Pagination' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + $ref: '#/components/responses/InternalServerError' + /bookings: + get: + operationId: get-bookings + summary: List existing bookings + description: Returns a list of all trips booking by the authenticated user. + tags: + - Bookings + responses: + '200': + description: A list of bookings + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Wrapper-Collection' + - properties: + data: + type: array + items: + $ref: '#/components/schemas/Booking' + - properties: + links: + allOf: + - $ref: '#/components/schemas/Links-Self' + - $ref: '#/components/schemas/Links-Pagination' + example: + data: + - id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + passenger_name: John Doe + has_bicycle: true + has_dog: true + - id: b2e783e1-c824-4d63-b37a-d8d698862f1d + trip_id: b2e783e1-c824-4d63-b37a-d8d698862f1d + passenger_name: Jane Smith + has_bicycle: false + has_dog: false + links: + self: https://api.example.com/bookings + next: https://api.example.com/bookings?page=2 + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/Wrapper-Collection' + - properties: + data: + type: array + xml: + name: bookings + wrapped: true + items: + $ref: '#/components/schemas/Booking' + - properties: + links: + allOf: + - $ref: '#/components/schemas/Links-Self' + - $ref: '#/components/schemas/Links-Pagination' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + $ref: '#/components/responses/InternalServerError' + post: + operationId: create-booking + summary: Create a booking + description: A booking is a temporary hold on a trip. It is not confirmed until the payment is processed. + tags: + - Bookings + security: + - OAuth2: + - write + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Booking' + application/xml: + schema: + $ref: '#/components/schemas/Booking' + responses: + '201': + description: Booking successful + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Booking' + - properties: + links: + $ref: '#/components/schemas/Links-Self' + + example: + id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + passenger_name: John Doe + has_bicycle: true + has_dog: true + links: + self: https://api.example.com/bookings/efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/Booking' + - properties: + links: + $ref: '#/components/schemas/Links-Self' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + $ref: '#/components/responses/InternalServerError' + + /bookings/{bookingId}: + parameters: + - name: bookingId + in: path + required: true + description: The ID of the booking to retrieve. + schema: + type: string + format: uuid + example: 1725ff48-ab45-4bb5-9d02-88745177dedb + get: + summary: Get a booking + description: Returns the details of a specific booking. + operationId: get-booking + tags: + - Bookings + responses: + '200': + description: The booking details + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Booking' + - properties: + links: + $ref: '#/components/schemas/Links-Self' + example: + id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + passenger_name: John Doe + has_bicycle: true + has_dog: true + links: + self: https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/Booking' + - properties: + links: + $ref: '#/components/schemas/Links-Self' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + summary: Delete a booking + description: Deletes a booking, cancelling the hold on the trip. + operationId: delete-booking + security: + - OAuth2: + - write + tags: + - Bookings + responses: + '204': + description: Booking deleted + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + $ref: '#/components/responses/InternalServerError' + + /bookings/{bookingId}/payment: + parameters: + - name: bookingId + in: path + required: true + description: The ID of the booking to pay for. + schema: + type: string + format: uuid + example: 1725ff48-ab45-4bb5-9d02-88745177dedb + post: + summary: Pay for a Booking + description: A payment is an attempt to pay for the booking, which will confirm the booking for the user and enable them to get their tickets. + operationId: create-booking-payment + tags: + - Payments + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BookingPayment' + examples: + Card: + summary: Card Payment + value: + amount: 49.99 + currency: gbp + source: + object: card + name: J. Doe + number: '4242424242424242' + cvc: 123 + exp_month: 12 + exp_year: 2025 + address_line1: 123 Fake Street + address_line2: 4th Floor + address_city: London + address_country: gb + address_post_code: N12 9XX + Bank: + summary: Bank Account Payment + value: + amount: 100.5 + currency: gbp + source: + object: bank_account + name: J. Doe + number: '00012345' + sort_code: '000123' + account_type: individual + bank_name: Starling Bank + country: gb + responses: + '200': + description: Payment successful + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/BookingPayment' + - properties: + links: + $ref: '#/components/schemas/Links-Booking' + examples: + Card: + summary: Card Payment + value: + id: 2e3b4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a + amount: 49.99 + currency: gbp + source: + object: card + name: J. Doe + number: '************4242' + cvc: 123 + exp_month: 12 + exp_year: 2025 + address_country: gb + address_post_code: N12 9XX + status: succeeded + links: + booking: https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb/payment + Bank: + summary: Bank Account Payment + value: + id: 2e3b4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a + amount: 100.5 + currency: gbp + source: + object: bank_account + name: J. Doe + account_type: individual + number: '*********2345' + sort_code: '000123' + bank_name: Starling Bank + country: gb + status: succeeded + links: + booking: https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + $ref: '#/components/responses/InternalServerError' +webhooks: + newBooking: + post: + operationId: new-booking + summary: New Booking + description: | + Subscribe to new bookings being created, to update integrations for your users. Related data is available via the links provided in the request. + tags: + - Bookings + requestBody: + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Booking' + - properties: + links: + allOf: + - $ref: '#/components/schemas/Links-Self' + - $ref: '#/components/schemas/Links-Pagination' + example: + id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + passenger_name: John Doe + has_bicycle: true + has_dog: true + links: + self: https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb + responses: + '200': + description: Return a 200 status to indicate that the data was received successfully. + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' +components: + securitySchemes: + OAuth2: + type: oauth2 + description: OAuth 2.0 authorization code following RFC8725 best practices. + flows: + authorizationCode: + authorizationUrl: https://example.com/oauth/authorize + tokenUrl: https://example.com/oauth/token + scopes: + read: Read access + write: Write access + schemas: + Station: + type: object + xml: + name: station + required: + - id + - name + - address + - country_code + properties: + id: + type: string + format: uuid + description: Unique identifier for the station. + examples: + - efdbb9d1-02c2-4bc3-afb7-6788d8782b1e + - b2e783e1-c824-4d63-b37a-d8d698862f1d + name: + type: string + description: The name of the station + examples: + - Berlin Hauptbahnhof + - Paris Gare du Nord + address: + type: string + description: The address of the station. + examples: + - Invalidenstraße 10557 Berlin, Germany + - 18 Rue de Dunkerque 75010 Paris, France + country_code: + type: string + description: The country code of the station. + format: iso-country-code + examples: + - DE + - FR + timezone: + type: string + description: The timezone of the station in the [IANA Time Zone Database format](https://www.iana.org/time-zones). + examples: + - Europe/Berlin + - Europe/Paris + Links-Self: + type: object + properties: + self: + type: string + format: uri + Links-Pagination: + type: object + properties: + next: + type: string + format: uri + prev: + type: string + format: uri + Problem: + xml: + name: problem + namespace: urn:ietf:rfc:7807 + properties: + type: + type: string + description: A URI reference that identifies the problem type + example: https://example.com/probs/out-of-credit + title: + type: string + description: A short, human-readable summary of the problem type + example: You do not have enough credit. + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem + example: Your current balance is 30, but that costs 50. + instance: + type: string + description: A URI reference that identifies the specific occurrence of the problem + example: /account/12345/msgs/abc + status: + type: integer + description: The HTTP status code + example: 400 + Trip: + type: object + xml: + name: trip + properties: + id: + type: string + format: uuid + description: Unique identifier for the trip + examples: + - 4f4e4e1-c824-4d63-b37a-d8d698862f1d + origin: + type: string + description: The starting station of the trip + examples: + - Berlin Hauptbahnhof + - Paris Gare du Nord + destination: + type: string + description: The destination station of the trip + examples: + - Paris Gare du Nord + - Berlin Hauptbahnhof + departure_time: + type: string + format: date-time + description: The date and time when the trip departs + examples: + - '2024-02-01T10:00:00Z' + arrival_time: + type: string + format: date-time + description: The date and time when the trip arrives + examples: + - '2024-02-01T16:00:00Z' + operator: + type: string + description: The name of the operator of the trip + examples: + - Deutsche Bahn + - SNCF + price: + type: number + description: The cost of the trip + examples: + - 50 + bicycles_allowed: + type: boolean + description: Indicates whether bicycles are allowed on the trip + dogs_allowed: + type: boolean + description: Indicates whether dogs are allowed on the trip + Booking: + type: object + xml: + name: booking + properties: + id: + type: string + format: uuid + description: Unique identifier for the booking + readOnly: true + examples: + - 3f3e3e1-c824-4d63-b37a-d8d698862f1d + trip_id: + type: string + format: uuid + description: Identifier of the booked trip + examples: + - 4f4e4e1-c824-4d63-b37a-d8d698862f1d + passenger_name: + type: string + description: Name of the passenger + examples: + - John Doe + has_bicycle: + type: boolean + description: Indicates whether the passenger has a bicycle. + has_dog: + type: boolean + description: Indicates whether the passenger has a dog. + Wrapper-Collection: + description: This is a generic request/response wrapper which contains both data and links which serve as hypermedia controls (HATEOAS). + type: object + properties: + data: + description: The wrapper for a collection is an array of objects. + type: array + items: + type: object + links: + description: A set of hypermedia links which serve as controls for the client. + type: object + readOnly: true + xml: + name: data + BookingPayment: + type: object + properties: + id: + description: Unique identifier for the payment. This will be a unique identifier for the payment, and is used to reference the payment in other objects. + type: string + format: uuid + readOnly: true + amount: + description: Amount intended to be collected by this payment. A positive decimal figure describing the amount to be collected. + type: number + exclusiveMinimum: 0 + examples: + - 49.99 + currency: + description: Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. + type: string + enum: + - bam + - bgn + - chf + - eur + - gbp + - nok + - sek + - try + source: + unevaluatedProperties: false + description: The payment source to take the payment from. This can be a card or a bank account. Some of these properties will be hidden on read to protect PII leaking. + anyOf: + - title: Card + description: A card (debit or credit) to take payment from. + properties: + object: + type: string + const: card + name: + type: string + description: Cardholder's full name as it appears on the card. + examples: + - Francis Bourgeois + number: + type: string + description: The card number, as a string without any separators. On read all but the last four digits will be masked for security. + examples: + - '4242424242424242' + cvc: + type: integer + description: Card security code, 3 or 4 digits usually found on the back of the card. + minLength: 3 + maxLength: 4 + writeOnly: true + + example: 123 + exp_month: + type: integer + format: int64 + description: Two-digit number representing the card's expiration month. + examples: + - 12 + exp_year: + type: integer + format: int64 + description: Four-digit number representing the card's expiration year. + examples: + - 2025 + address_line1: + type: string + writeOnly: true + address_line2: + type: string + writeOnly: true + address_city: + type: string + address_country: + type: string + address_post_code: + type: string + required: + - name + - number + - cvc + - exp_month + - exp_year + - address_country + - title: Bank Account + description: A bank account to take payment from. Must be able to make payments in the currency specified in the payment. + type: object + properties: + object: + const: bank_account + type: string + name: + type: string + number: + type: string + description: The account number for the bank account, in string form. Must be a current account. + sort_code: + type: string + description: The sort code for the bank account, in string form. Must be a six-digit number. + account_type: + enum: + - individual + - company + type: string + description: The type of entity that holds the account. This can be either `individual` or `company`. + bank_name: + type: string + description: The name of the bank associated with the routing number. + examples: + - Starling Bank + country: + type: string + description: Two-letter country code (ISO 3166-1 alpha-2). + required: + - name + - number + - account_type + - bank_name + - country + status: + description: The status of the payment, one of `pending`, `succeeded`, or `failed`. + type: string + enum: + - pending + - succeeded + - failed + readOnly: true + Links-Booking: + type: object + properties: + booking: + type: string + format: uri + examples: + - https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb + headers: + RateLimit: + description: | + The RateLimit header is communicate quota policies, and contains a `limit` to + conveys the expiring limit, `remaining` to convey the remaining quota units, + and `reset` to convey the time window reset time. + schema: + type: string + examples: + - limit=10, remaining=0, reset=10 + + Retry-After: + description: | + The Retry-After header indicates how long the user agent should wait before making a follow-up request. + The value is in seconds and can be an integer or a date in the future. + If the value is an integer, it indicates the number of seconds to wait. + If the value is a date, it indicates the time at which the user agent should make a follow-up request. + schema: + type: string + examples: + integer: + value: '120' + summary: Retry after 120 seconds + date: + value: 'Fri, 31 Dec 2021 23:59:59 GMT' + summary: Retry after the specified date + + responses: + BadRequest: + description: Bad Request + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/bad-request + title: Bad Request + status: 400 + detail: The request is invalid or missing required parameters. + application/problem+xml: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/bad-request + title: Bad Request + status: 400 + detail: The request is invalid or missing required parameters. + + Conflict: + description: Conflict + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/conflict + title: Conflict + status: 409 + detail: There is a conflict with an existing resource. + application/problem+xml: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/conflict + title: Conflict + status: 409 + detail: There is a conflict with an existing resource. + + Forbidden: + description: Forbidden + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/forbidden + title: Forbidden + status: 403 + detail: Access is forbidden for the provided credentials. + application/problem+xml: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/forbidden + title: Forbidden + status: 403 + detail: Access is forbidden for the provided credentials. + + InternalServerError: + description: Internal Server Error + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/internal-server-error + title: Internal Server Error + status: 500 + detail: An unexpected error occurred. + application/problem+xml: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/internal-server-error + title: Internal Server Error + status: 500 + detail: An unexpected error occurred. + + NotFound: + description: Not Found + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/not-found + title: Not Found + status: 404 + detail: The requested resource was not found. + application/problem+xml: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/not-found + title: Not Found + status: 404 + detail: The requested resource was not found. + + TooManyRequests: + description: Too Many Requests + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + Retry-After: + $ref: '#/components/headers/Retry-After' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/too-many-requests + title: Too Many Requests + status: 429 + detail: You have exceeded the rate limit. + application/problem+xml: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/too-many-requests + title: Too Many Requests + status: 429 + detail: You have exceeded the rate limit. + + Unauthorized: + description: Unauthorized + headers: + RateLimit: + $ref: '#/components/headers/RateLimit' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/unauthorized + title: Unauthorized + status: 401 + detail: You do not have the necessary permissions. + application/problem+xml: + schema: + $ref: '#/components/schemas/Problem' + example: + type: https://example.com/errors/unauthorized + title: Unauthorized + status: 401 + detail: You do not have the necessary permissions. From d7a1b2d1c83793dff1c7eb5f1ba4ffc4621f20b4 Mon Sep 17 00:00:00 2001 From: gkoberger Date: Fri, 15 Mar 2024 14:01:02 -0400 Subject: [PATCH 2/2] license --- 3.1/json/train-travel.json | 3 ++- 3.1/yaml/train-travel.yaml | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/3.1/json/train-travel.json b/3.1/json/train-travel.json index 997d0b8..28dd626 100644 --- a/3.1/json/train-travel.json +++ b/3.1/json/train-travel.json @@ -11,7 +11,8 @@ }, "license": { "name": "Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International", - "identifier": "CC-BY-NC-SA-4.0" + "identifier": "CC-BY-NC-SA-4.0", + "url": "https://github.com/bump-sh-examples/train-travel-api/blob/main/LICENSE_CC-BY-NC-SA-4.0" } }, "x-topics": [ diff --git a/3.1/yaml/train-travel.yaml b/3.1/yaml/train-travel.yaml index 04804a1..b37cc93 100644 --- a/3.1/yaml/train-travel.yaml +++ b/3.1/yaml/train-travel.yaml @@ -10,6 +10,7 @@ info: license: name: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International identifier: CC-BY-NC-SA-4.0 + url: https://github.com/bump-sh-examples/train-travel-api/blob/main/LICENSE_CC-BY-NC-SA-4.0 x-topics: - title: Getting started