{
  "swagger": "2.0",
  "info": {
    "title": "MAX",
    "version": "0.1.0",
    "description": "MAX PC-MID API"
  },
  "host": "localhost:10098",
  "basePath": "/",
  "schemes": [
    "https"
  ],
  "tags": [
    {
      "name": "enrol",
      "description": "Enrol an application so that it can use the MAX API."
    },
    {
      "name": "roles",
      "description": "Fetch and request roles information."
    }
  ],
  "paths": {
    "/MAXAPI/venue-api-root-cert": {
      "get": {
        "tags": [
          "enrol"
        ],
        "summary": "Establish trust between client and server",
        "description": "The purpose of visiting this endpoint is to retrieve the Root CA of this server's certificate. This is provided so that the client can store the Root CA certificate in it's trusted key store.\n\nWhen making a request, the client should not verify the server's certificate against a list of certificate authorities (CAs).\n",
        "responses": {
          "200": {
            "$ref": "#/responses/CACertificate"
          }
        }
      }
    },
    "/enrol": {
      "get": {
        "tags": [
          "enrol"
        ],
        "summary": "Establish trust between client and server",
        "description": "The purpose of visiting this endpoint is to make an initial request to allow the client and server to handshake, so that the client can use the previously retrieved CA to verify the Server's certificate.\n",
        "responses": {
          "204": {
            "description": "No content"
          }
        }
      },
      "post": {
        "tags": [
          "enrol"
        ],
        "summary": "Enrol with the client's CSR",
        "description": "The purpose of visiting this endpoint is to allow the client to upload a certificate signing request (CSR) and for the server to return a signed certificate to allow secure communication.",
        "consumes": [
          "application/pkcs10"
        ],
        "produces": [
          "application/x-x509-ca-cert",
          "application/x-pem-file"
        ],
        "parameters": [
          {
            "in": "body",
            "name": "csr",
            "description": "CSR (certificate signing request)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Enrolment successful",
            "schema": {
              "type": "file"
            }
          },
          "400": {
            "$ref": "#/responses/InvalidCSR"
          },
          "406": {
            "$ref": "#/responses/CertTypeNotAcceptable"
          }
        }
      }
    },
    "/roles": {
      "get": {
        "tags": [
          "roles"
        ],
        "summary": "Fetch information on roles",
        "description": "This purpose of visiting this endpoint is to allow the client to find out the status as to whether or not the requested roles have been granted or not.",
        "responses": {
          "200": {
            "$ref": "#/responses/RolesResponse"
          },
          "403": {
            "$ref": "#/responses/AccessDenied"
          },
          "404": {
            "$ref": "#/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "roles"
        ],
        "summary": "Request roles",
        "description": "This purpose of visiting this endpoint is to allow the client to request roles that will provide appropriate permission for the third party application type.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "body",
            "name": "roles",
            "description": "Roles requested by the client",
            "schema": {
              "$ref": "#/definitions/RolesRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "$ref": "#/responses/RolesResponse"
          },
          "400": {
            "$ref": "#/responses/RolesBadRequest"
          },
          "403": {
            "$ref": "#/responses/AccessDenied"
          }
        }
      }
    }
  },
  "responses": {
    "CACertificate": {
      "description": "CA certificate",
      "schema": {
        "$ref": "#/definitions/CAResponse"
      }
    },
    "RolesResponse": {
      "description": "Get roles and permissions info",
      "schema": {
        "$ref": "#/definitions/RolesResponse"
      }
    },
    "AccessDenied": {
      "description": "User does not have access to page",
      "schema": {
        "$ref": "#/definitions/AccessDenied"
      }
    },
    "RolesBadRequest": {
      "description": "Bad request",
      "schema": {
        "$ref": "#/definitions/APIError"
      }
    },
    "NotFound": {
      "description": "Not found",
      "schema": {
        "$ref": "#/definitions/APIError"
      }
    },
    "InvalidCSR": {
      "description": "Invalid CSR",
      "schema": {
        "$ref": "#/definitions/APIError"
      }
    },
    "CertTypeNotAcceptable": {
      "description": "Certificate type is not acceptable",
      "schema": {
        "$ref": "#/definitions/APIError"
      }
    }
  },
  "definitions": {
    "AccessDenied": {
      "type": "string"
    },
    "RolesRequest": {
      "type": "object",
      "required": [
        "roles"
      ],
      "properties": {
        "roles": {
          "$ref": "#/definitions/RolesRequestRoles"
        }
      },
      "example": {
        "roles": [
          "superuser",
          "venue-api-consumer"
        ]
      }
    },
    "RolesRequestRoles": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "APIError": {
      "type": "object",
      "required": [
        "status",
        "title",
        "detail"
      ],
      "properties": {
        "status": {
          "type": "string",
          "description": "HTTP status text description"
        },
        "title": {
          "type": "string",
          "description": "Quick description of the error"
        },
        "detail": {
          "type": "string",
          "description": "More detail on the error"
        }
      }
    },
    "CAResponse": {
      "type": "string"
    },
    "RolesResponse": {
      "type": "object",
      "properties": {
        "roles": {
          "$ref": "#/definitions/RolesResponseRoles"
        }
      },
      "example": {
        "roles": {
          "approved": [
            "venue-api-consumer"
          ],
          "desired": [
            "jackpot"
          ]
        }
      }
    },
    "RolesResponseRoles": {
      "type": "object",
      "properties": {
        "approved": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "desired": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}