{
	"swagger": "2.0",
	"info": {
		"title": "Railcard Validation Service",
		"version": "v2"
	},
	"paths": {
		"/api/v2/railcards/{railcardNumber}/expiry": {
			"post": {
				"description": "This method is used to check an individual railcard and will return the expiry date if a matching railcard is found.\n",
				"consumes": [
					"application/json"
				],
				"produces": [
					"application/json"
				],
				"parameters": [
					{
						"name": "Authorization",
						"description": "Bearer token",
						"required": true,
						"in": "header",
						"type": "string"
					},
					{
						"name": "client_id",
						"description": "Unique client id identifying the organisation making the request",
						"required": true,
						"in": "header",
						"type": "string"
					},
					{
						"name": "X-Correlation-Cust-Id",
						"description": "Unique client correlation id that can be used to trace requests",
						"required": false,
						"in": "header",
						"type": "string"
					},
					{
						"name": "Accept-Encoding",
						"description": "Indicates the content encoding that the client can understand. Specifying gzip will result in compressed responses.",
						"required": false,
						"in": "header",
						"type": "string"
					},
					{
						"name": "User-Agent",
						"description": "Name and version number of system making the request, e.g. RDGRuntime/7.41.2",
						"required": true,
						"in": "header",
						"type": "string"
					},
					{
						"name": "railcardNumber",
						"required": true,
						"in": "path",
						"type": "string",
						"maxLength": 50
					},
					{
						"x-amf-mediaType": "application/json",
						"required": true,
						"in": "body",
						"name": "body",
						"schema": {
							"$ref": "#/definitions/RailcardRequest"
						}
					}
				],
				"responses": {
					"200": {
						"description": "A valid railcard matching the provided details was found",
						"x-amf-mediaType": "application/json",
						"schema": {
							"$ref": "#/definitions/RailcardResponse"
						}
					},
					"400": {
						"description": "The server cannot process the request due to a client error",
						"x-amf-mediaType": "application/json",
						"schema": {
							"$ref": "#/definitions/Errors"
						}
					},
					"401": {
						"description": "The user is not authorised to use this API",
						"x-amf-mediaType": "application/json",
						"schema": {
							"$ref": "#/definitions/Errors"
						}
					},
					"404": {
						"description": "The server did not find a valid railcard with the provided details",
						"x-amf-mediaType": "application/json",
						"schema": {
							"$ref": "#/definitions/Errors"
						}
					},
					"500": {
						"description": "The server encountered an unexpected condition that prevented it from fulfilling the request",
						"x-amf-mediaType": "application/json",
						"schema": {
							"$ref": "#/definitions/Errors"
						}
					}
				}
			}
		},
		"/api/v2/railcards/validityChanges": {
			"post": {
				"description": "This method is used to retrieve changes in railcard validities during a specified time window.\n",
				"consumes": [
					"application/json"
				],
				"produces": [
					"application/json"
				],
				"parameters": [
					{
						"name": "Authorization",
						"description": "Bearer token",
						"required": true,
						"in": "header",
						"type": "string"
					},
					{
						"name": "client_id",
						"description": "Unique client id identifying the organisation making the request",
						"required": true,
						"in": "header",
						"type": "string"
					},
					{
						"name": "X-Correlation-Cust-Id",
						"description": "Unique client correlation id that can be used to trace requests",
						"required": false,
						"in": "header",
						"type": "string"
					},
					{
						"name": "Accept-Encoding",
						"description": "Indicates the content encoding that the client can understand. Specifying gzip will result in compressed responses.",
						"required": false,
						"in": "header",
						"type": "string"
					},
					{
						"name": "User-Agent",
						"description": "Name and version number of system making the request, e.g. RDGRuntime/7.41.2",
						"required": true,
						"in": "header",
						"type": "string"
					},
					{
						"name": "limit",
						"description": "Used with offset to enable pagination. Specifies how many records to return.",
						"in": "query",
						"required": true,
						"type": "integer"
					},
					{
						"name": "offset",
						"description": "Used with limit to enable pagination. Specifies which record to start from. It is set to 0 for the initial request and to the value supplied in the previous response for subsequent requests. Note: When the offset is returned as 0 in a response this means there are no more railcards to retrieve within the specified time window",
						"in": "query",
						"required": true,
						"type": "integer"
					},
					{
						"x-amf-mediaType": "application/json",
						"required": true,
						"in": "body",
						"name": "body",
						"schema": {
							"$ref": "#/definitions/ValidityChangeRequest"
						}
					}
				],
				"responses": {
					"200": {
						"description": "List of railcards whose validity status has changed",
						"x-amf-mediaType": "application/json",
						"schema": {
							"$ref": "#/definitions/ValidityChangeResponse"
						}
					},
					"400": {
						"description": "The server cannot process the request due to a client error",
						"x-amf-mediaType": "application/json",
						"schema": {
							"$ref": "#/definitions/Errors"
						}
					},
					"401": {
						"description": "The user is not authorised to use this API",
						"x-amf-mediaType": "application/json",
						"schema": {
							"$ref": "#/definitions/Errors"
						}
					},
					"404": {
						"description": "The server did not find a valid railcard with the provided details",
						"x-amf-mediaType": "application/json",
						"schema": {
							"$ref": "#/definitions/Errors"
						}
					},
					"500": {
						"description": "The server encountered an unexpected condition that prevented it from fulfilling the request",
						"x-amf-mediaType": "application/json",
						"schema": {
							"$ref": "#/definitions/Errors"
						}
					}
				}
			}
		}
	},
	"definitions": {
		"ValidityChangeRequest": {
			"title": "Validity change request",
			"description": "Request list of railcards whose validity has changed within a time window",
			"type": "object",
			"required": [
				"from",
				"to"
			],
			"properties": {
				"from": {
					"description": "Specify the beginning of the time window to search for railcard validity changes",
					"type": "string",
					"format": "date-time"
				},
				"to": {
					"description": "Specify the end of the time window to search for railcard validity changes",
					"type": "string",
					"format": "date-time"
				},
				"includeExpired": {
					"description": "Determines whether the response should include expired Railcards. Note: Not currently enabled within RDG back office, so setting this parameter will have no effect",
					"type": "boolean",
					"default": false
				},
				"railcardTypes": {
					"description": "Determines the Railcard Types to query and return. <BR/>If empty or parameter not present, this means include all known Railcards in the system. Examples include: SRN,YNG,DIS,NEW,2TR,FAM,TST,VET,TSU",
					"type": "array",
					"items": {
						"$ref": "#/definitions/RailcardType"
					}
				},
				"validityChangeTypes": {
					"description": "Determines the Railcard Types to query and return. <BR/>If empty or parameter not present, this means include all known Validity Change Types",
					"type": "array",
					"items": {
						"$ref": "#/definitions/ValidityChangeType"
					}
				}
			}
		},
		"ValidityChangeType": {
			"type": "string",
			"enum": [
				"VALID_TO_INVALID",
				"INVALID_TO_VALID"
			]
		},
		"RailcardType": {
			"type": "string",
			"minLength": 3,
			"maxLength": 3,
			"description": "The type code for the Railcard, this is the Product Code for the Railcard."
		},
		"ValidityChangeResponse": {
			"title": "Validity change response",
			"description": "List of railcards whose validity has changed within the requested time window",
			"type": "object",
			"required": [
				"from",
				"to",
				"sourceDataSyncTime",
				"offset",
				"validityChanges"
			],
			"properties": {
				"from": {
					"description": "Return the from parameter from the request",
					"type": "string",
					"format": "date-time"
				},
				"to": {
					"description": "Return the to parameter from the request",
					"type": "string",
					"format": "date-time"
				},
				"offset": {
					"description": "Used for pagination. 0 means no more pages, a non-zero value should be used when requesting the next page",
					"type": "integer"
				},
				"sourceDataSyncTime": {
					"description": "Informs the client when the data was last successfully gathered by RDG from all railcard data sources. The client would normally use this value as the 'from' parameter in their next sequence of calls (i.e. after they have completed the any current sequence of pagination calls)",
					"type": "string",
					"format": "date-time"
				},
				"validityChanges": {
					"description": "Requested validity changes",
					"type": "array",
					"minItems": 0,
					"items": {
						"$ref": "#/definitions/ValidityChange"
					}
				}
			}
		},
		"ValidityChange": {
			"title": "Validity change",
			"description": "Details of railcards whose validity has changed",
			"type": "object",
			"required": [
				"railcardNumber",
				"railcardType",
				"expiresOn",
				"isValid",
				"newState",
				"changedAt"
			],
			"properties": {
				"railcardNumber": {
					"title": "Railcard Number",
					"description": "Identifier for a Railcard",
					"type": "string",
					"maxLength": 50,
					"minLength": 0
				},
				"railcardType": {
					"title": "Railcard Type",
					"description": "The type code for the Railcard, this is the Product Code for the Railcard",
					"type": "string",
					"maxLength": 3,
					"minLength": 3
				},
				"expiresOn": {
					"title": "Expires On",
					"description": "Date of Railcard expiry",
					"type": "string",
					"format": "date"
				},
				"isValid": {
					"description": "States whether the new Railcard state is valid (true) or not (false)",
					"type": "boolean"
				},
				"newState": {
					"description": "The new Railcard state",
					"type": "string",
					"minLength": 0,
					"maxLength": 255
				},
				"changedAt": {
					"description": "Datetime the change occurred",
					"type": "string",
					"format": "date-time"
				}
			}
		},
		"RailcardResponse": {
			"title": "Railcard response",
			"description": "Railcard response details",
			"type": "object",
			"required": [
				"expiresOn"
			],
			"properties": {
				"expiresOn": {
					"title": "Expires On",
					"description": "Date on which the Railcard expires",
					"type": "string",
					"format": "date"
				}
			}
		},
		"RailcardRequest": {
			"title": "Railcard request",
			"description": "Railcard request details",
			"type": "object",
			"required": [
				"railcardType",
				"expiresOn",
				"holders"
			],
			"properties": {
				"railcardType": {
					"title": "Railcard Type",
					"description": "The type code for the Railcard, this is the Product Code for the Railcard",
					"type": "string",
					"maxLength": 10,
					"minLength": 0
				},
				"expiresOn": {
					"title": "Expires On",
					"description": "Expiry date for the Railcard",
					"type": "string",
					"format": "date"
				},
				"holders": {
					"type": "array",
					"items": {
						"$ref": "#/definitions/RailcardHolder"
					}
				}
			}
		},
		"Errors": {
			"title": "Error Array",
			"type": "object",
			"properties": {
				"errors": {
					"type": "array",
					"items": {
						"$ref": "#/definitions/Error"
					}
				}
			}
		},
		"RailcardHolder": {
			"title": "Railcard Holder",
			"description": "Railcard holder(s) associated with Railcard",
			"type": "object",
			"required": [
				"lastName"
			],
			"properties": {
				"firstName": {
					"title": "First Name",
					"description": "First name of a cardholder",
					"type": "string",
					"maxLength": 50,
					"minLength": 0
				},
				"lastName": {
					"title": "Last Name",
					"description": "Last name of a cardholder",
					"type": "string",
					"maxLength": 50,
					"minLength": 0
				}
			}
		},
		"Error": {
			"title": "RDG Error Object",
			"type": "object",
			"properties": {
				"code": {
					"title": "Error Code",
					"type": "string",
					"description": "A unique (by service) code for an error"
				},
				"message": {
					"title": "Error Message",
					"type": "string",
					"description": "Short description of an error"
				},
				"timestamp": {
					"title": "Error Timestamp",
					"type": "string",
					"format": "date-time",
					"description": "Timestamp of an error"
				},
				"context": {
					"title": "Context",
					"description": "Additional context in relation to the error.",
					"type": "object",
					"patternProperties": {
						"[a-zA-Z0-9_]*": {
							"type": "string"
						}
					}
				}
			}
		}
	}
}