{
  "openapi": "3.0.1",
  "info": {
    "title": "Register of Interests API",
    "description": "API to allow users to query and download the register of Members interests.",
    "contact": {
      "name": "UK Parliament",
      "url": "https://www.parliament.uk/",
      "email": "softwareengineering@parliament.uk"
    },
    "version": "v1"
  },
  "paths": {
    "/api/v1/Categories": {
      "get": {
        "tags": [
          "Categories"
        ],
        "summary": "Return a list of categories interests should be registered under, sorted by category number.",
        "parameters": [
          {
            "name": "Skip",
            "in": "query",
            "description": "The number of records to skip from the first, default is 0.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          },
          {
            "name": "Take",
            "in": "query",
            "description": "The number of records to return, default is 20.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublishedCategoryApiLinkedSearchResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ObjectApiResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/Categories/{id}": {
      "get": {
        "tags": [
          "Categories"
        ],
        "summary": "Return details of an interest category by ID.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID of the category.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublishedCategory"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ObjectApiResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/Interests": {
      "get": {
        "tags": [
          "Interests"
        ],
        "summary": "Return a list of interests that have been published on a register.",
        "parameters": [
          {
            "name": "MemberId",
            "in": "query",
            "description": "Search for an interest created by member with this ID.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "CategoryId",
            "in": "query",
            "description": "Search for an interest within a specific category with this ID.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "PublishedFrom",
            "in": "query",
            "description": "Search for an interest published on or after this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "PublishedTo",
            "in": "query",
            "description": "Search for an interest published on or before this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "RegisteredFrom",
            "in": "query",
            "description": "Search for an interest registered on or after this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "RegisteredTo",
            "in": "query",
            "description": "Search for an interest registered on or before this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "UpdatedFrom",
            "in": "query",
            "description": "Search for an interest which has any updates on or after this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "UpdatedTo",
            "in": "query",
            "description": "Search for an interest which has any updates on or before this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "RegisterId",
            "in": "query",
            "description": "Search for an interest published in a register with this ID. If not provided, default value is latest register ID.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "ExpandChildInterests",
            "in": "query",
            "description": "If true returns related interests in a nested format, rather than as individual items.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Take",
            "in": "query",
            "description": "The number of records to return, default is 20. Maximum is 20.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 20
            }
          },
          {
            "name": "SortOrder",
            "in": "query",
            "description": "The order in which to return records.",
            "schema": {
              "$ref": "#/components/schemas/InterestsSortOrder"
            }
          },
          {
            "name": "Skip",
            "in": "query",
            "description": "The number of records to skip from the first, default is 0.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublishedInterestApiLinkedSearchResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ObjectApiResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/Interests/csv": {
      "get": {
        "tags": [
          "Interests"
        ],
        "summary": "Return interests that have been published on a register as a collection of CSVs packaged in a ZIP file.",
        "description": "If the result set is an empty, an empty ZIP will be returned.",
        "parameters": [
          {
            "name": "MemberId",
            "in": "query",
            "description": "Search for an interest created by member with this ID.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "CategoryId",
            "in": "query",
            "description": "Search for an interest with associated category with this ID.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "PublishedFrom",
            "in": "query",
            "description": "Search for an interest published on or after this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "PublishedTo",
            "in": "query",
            "description": "Search for an interest published on or before this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "RegisteredFrom",
            "in": "query",
            "description": "Search for an interest registered on or after this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "RegisteredTo",
            "in": "query",
            "description": "Search for an interest registered on or before this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "UpdatedFrom",
            "in": "query",
            "description": "Search for an interest which has any updates on or after this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "UpdatedTo",
            "in": "query",
            "description": "Search for an interest which has any updates on or before this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "RegisterId",
            "in": "query",
            "description": "Search for an interest published in a register with this ID. If not provided, default value is latest register ID.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "IncludeFieldDescriptions",
            "in": "query",
            "description": "Returns a metadata file for each category, containing a list of fields which are available for a member to add further information about the interest.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/v1/Interests/{id}": {
      "get": {
        "tags": [
          "Interests"
        ],
        "summary": "Return the latest version of an interest which has been published.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID of the interest.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublishedInterest"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ObjectApiResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/Registers": {
      "get": {
        "tags": [
          "Registers"
        ],
        "summary": "Return a list of published versions of registers of interests.",
        "parameters": [
          {
            "name": "SessionId",
            "in": "query",
            "description": "Search for registers published within a parliamentary session with this ID. Find session data at https://whatson-api.parliament.uk/.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "Skip",
            "in": "query",
            "description": "The number of records to skip from the first, default is 0.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          },
          {
            "name": "Take",
            "in": "query",
            "description": "The number of records to return, default is 20.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublishedRegisterApiLinkedSearchResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/Registers/{id}": {
      "get": {
        "tags": [
          "Registers"
        ],
        "summary": "Return a published version of a register of interests by ID.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID of the register.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublishedRegister"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/Registers/{id}/document": {
      "get": {
        "tags": [
          "Registers"
        ],
        "summary": "Return a published register as a PDF document by ID.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID of the register.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Whether to return a document containing the full register or only updates. Default value is Full.",
            "schema": {
              "$ref": "#/components/schemas/RegisterDocument"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiResponseError": {
        "type": "object",
        "properties": {
          "errorType": {
            "$ref": "#/components/schemas/ApiResponseErrorType"
          },
          "errorMessages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ApiResponseErrorType": {
        "enum": [
          "ValidationError",
          "AuthenticationError",
          "ConnectivityError",
          "GenericError"
        ],
        "type": "string"
      },
      "Field": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "type": {
            "type": "string",
            "nullable": true
          },
          "typeInfo": {
            "$ref": "#/components/schemas/FieldTypeInfo"
          },
          "value": {
            "nullable": true
          },
          "values": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Field"
              }
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "FieldTypeInfo": {
        "type": "object",
        "properties": {
          "currencyCode": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "InterestsSortOrder": {
        "enum": [
          "PublishingDateDescending",
          "CategoryAscending"
        ],
        "type": "string",
        "description": "The order in which interests endpoints should return results."
      },
      "Link": {
        "type": "object",
        "properties": {
          "rel": {
            "type": "string",
            "description": "Relationship of the link to the object requested.",
            "nullable": true
          },
          "href": {
            "type": "string",
            "description": "A complete URL that shows how the action can be performed.",
            "nullable": true
          },
          "method": {
            "type": "string",
            "description": "Request method of the link.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "HATEOAS Link for retrieving related information to a response or object."
      },
      "Member": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "ID of the member.",
            "format": "int32"
          },
          "nameDisplayAs": {
            "type": "string",
            "description": "Member's current full name, as it should be displayed in text.",
            "nullable": true
          },
          "nameListAs": {
            "type": "string",
            "description": "Member's current name in the format {surname}, {forename}, for use in an ordered list.",
            "nullable": true
          },
          "house": {
            "type": "string",
            "description": "The name of the House the Member is currently associated with.",
            "nullable": true
          },
          "memberFrom": {
            "type": "string",
            "description": "Constituency of Commons Members.",
            "nullable": true
          },
          "party": {
            "type": "string",
            "description": "Party the Member is currently associated with.",
            "nullable": true
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            },
            "description": "A list of HATEOAS Links for retrieving further information about this member.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Member of Parliament who has registered the interest."
      },
      "ObjectApiResponse": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ApiResponseError"
          },
          "response": {
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "detail": {
            "type": "string",
            "nullable": true
          },
          "instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": { }
      },
      "PublishedCategory": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "ID of the category.",
            "format": "int32"
          },
          "number": {
            "type": "string",
            "description": "Number of the category in the code of conduct.",
            "nullable": true
          },
          "name": {
            "type": "string",
            "description": "Name of the category.",
            "nullable": true
          },
          "parentCategoryIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int32"
            },
            "description": "The unique ID for any parent category to which this category is associated, if the category is associated with another category.",
            "nullable": true
          },
          "type": {
            "$ref": "#/components/schemas/RegisterType"
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            },
            "description": "A list of HATEOAS Links for retrieving further information about this category.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Category an interest can be registered with."
      },
      "PublishedCategoryApiLinkedSearchResult": {
        "type": "object",
        "properties": {
          "skip": {
            "type": "integer",
            "description": "The skip value that was used in the query.",
            "format": "int32"
          },
          "take": {
            "type": "integer",
            "description": "The take value that was used in the query.",
            "format": "int32"
          },
          "totalResults": {
            "type": "integer",
            "description": "The total number of results which matches the query.",
            "format": "int32"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublishedCategory"
            },
            "description": "The list of items found for the specified page (by requested skip and take).",
            "nullable": true
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            },
            "description": "A list of HATEOAS Links for navigating through the paginated result.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Paginated search result with HATEOAS Links."
      },
      "PublishedInterest": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "ID of the interest.",
            "format": "int32"
          },
          "summary": {
            "type": "string",
            "description": "Title Summary for the interest.",
            "nullable": true
          },
          "parentInterestId": {
            "type": "integer",
            "description": "The unique ID for the payer (parent interest) to which this payment (child interest) is associated.",
            "format": "int32",
            "nullable": true
          },
          "registrationDate": {
            "type": "string",
            "description": "Registration Date on the published interest.",
            "format": "date",
            "nullable": true
          },
          "publishedDate": {
            "type": "string",
            "description": "Date when the interest was first published.",
            "format": "date",
            "nullable": true
          },
          "updatedDates": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date"
            },
            "description": "A list of dates on which the interest has been updated since it has been published.",
            "nullable": true
          },
          "category": {
            "$ref": "#/components/schemas/PublishedCategory"
          },
          "member": {
            "$ref": "#/components/schemas/Member"
          },
          "fields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Field"
            },
            "description": "List of fields which are available for a member to add further information about the interest.",
            "nullable": true
          },
          "childInterests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublishedInterest"
            },
            "description": "List of Interests which are sub interests of this interest. This property is only present if `ExpandChildInterests` is true, and is not defined by default.",
            "nullable": true
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            },
            "description": "A list of HATEOAS Links for retrieving related information about this interest.",
            "nullable": true
          },
          "rectified": {
            "type": "boolean",
            "description": "Whether the interest has been rectified (e.g. when the interest was submitted late)."
          },
          "rectifiedDetails": {
            "type": "string",
            "description": "The reason that the interest was rectified, or `null` if the interest was not rectified.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Version of an interest which has been published."
      },
      "PublishedInterestApiLinkedSearchResult": {
        "type": "object",
        "properties": {
          "skip": {
            "type": "integer",
            "description": "The skip value that was used in the query.",
            "format": "int32"
          },
          "take": {
            "type": "integer",
            "description": "The take value that was used in the query.",
            "format": "int32"
          },
          "totalResults": {
            "type": "integer",
            "description": "The total number of results which matches the query.",
            "format": "int32"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublishedInterest"
            },
            "description": "The list of items found for the specified page (by requested skip and take).",
            "nullable": true
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            },
            "description": "A list of HATEOAS Links for navigating through the paginated result.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Paginated search result with HATEOAS Links."
      },
      "PublishedRegister": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "ID of the register.",
            "format": "int32"
          },
          "publishedDate": {
            "type": "string",
            "description": "Date when the Register was published.",
            "format": "date"
          },
          "type": {
            "$ref": "#/components/schemas/RegisterType"
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            },
            "description": "A list of HATEOAS Links for retrieving related information about this register.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A published version of a register of interests."
      },
      "PublishedRegisterApiLinkedSearchResult": {
        "type": "object",
        "properties": {
          "skip": {
            "type": "integer",
            "description": "The skip value that was used in the query.",
            "format": "int32"
          },
          "take": {
            "type": "integer",
            "description": "The take value that was used in the query.",
            "format": "int32"
          },
          "totalResults": {
            "type": "integer",
            "description": "The total number of results which matches the query.",
            "format": "int32"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublishedRegister"
            },
            "description": "The list of items found for the specified page (by requested skip and take).",
            "nullable": true
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            },
            "description": "A list of HATEOAS Links for navigating through the paginated result.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Paginated search result with HATEOAS Links."
      },
      "RegisterDocument": {
        "enum": [
          "Full",
          "Updated"
        ],
        "type": "string",
        "description": "Whether a document contains the full register or only updates"
      },
      "RegisterType": {
        "enum": [
          "Commons"
        ],
        "type": "string",
        "description": "The type of register of interests"
      }
    }
  }
}