{
  "openapi": "3.0.2",
  "info": {
    "description": "Provides a basic search api against the National API Directory of Norway",
    "version": "1.2",
    "title": "National API Directory Search API",
    "termsOfService": "https://fellesdatakatalog.brreg.no/about",
    "contact": {
      "name": "Brønnøysundregistrene",
      "url": "https://fellesdatakatalog.brreg.no",
      "email": "fellesdatakatalog@brreg.no"
    },
    "license": {
      "name": "License of API",
      "url": "http://data.norge.no/nlod/no/2.0"
    }
  },
  "externalDocs": {
    "description": "Dokumentasjon på Informasjonsforvaltning GitHub",
    "url": "https://informasjonsforvaltning.github.io/felles-datakatalog/api-katalog/api/"
  },
  "servers": [
    {
      "url": "https://fellesdatakatalog.brreg.no/api/apis",
      "description": "The production API server"
    }
  ],
  "tags": [
    {
      "name": "rest-controller",
      "description": "REST Controller"
    },
    {
      "name": "search-controller",
      "description": "Search Controller"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": [
          "search-controller"
        ],
        "summary": "Queries the api catalog for api specifications",
        "description": "So far only simple queries is supported",
        "operationId": "searchUsingGET",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "the query string",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "orgPath",
            "in": "query",
            "description": "Filters on publisher's organization path (orgPath), e.g. /STAT/972417858/971040238",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "harvestSourceUri",
            "in": "query",
            "description": "Filters on harvestSourceUri external identifier",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "description": "Filters on formats",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "aggregations",
            "in": "query",
            "description": "Calculate aggregations",
            "required": false,
            "schema": {
              "type": "string",
              "default": "false"
            }
          },
          {
            "name": "sortfield",
            "in": "query",
            "description": "Specifies the sort field, at the present the only value is \\\"modified\\\". Default is no value, and results are sorted by relevance",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sortdirection",
            "in": "query",
            "description": "Specifies the sort direction of the sorted result. The directions are: asc for ascending and desc for descending",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryResponse"
                }
              }
            }
          }
        }
      }
    },
    "/{id}": {
      "get": {
        "tags": [
          "rest-controller"
        ],
        "summary": "Get a specific api",
        "operationId": "getApiDocumentUsingGET",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiDocument"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/{id}/schema": {
      "get": {
        "tags": [
          "rest-controller"
        ],
        "summary": "Get a specific api's specification",
        "operationId": "getApiSpecUsingGET",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSpec"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/endpoints": {
      "get": {
        "tags": [
          "search-controller"
        ],
        "summary": "Queries the api catalog for api specifications",
        "description": "dedicated path to serve endpoints based on organization and/or standard",
        "operationId": "searchUsingGETwithEndpointRespons",
        "parameters": [
          {
            "name": "serviceType (\"tjenestetype\")",
            "in": "query",
            "description": "Filters on standard (\"type of service\")",
            "required": true,
            "schema": {
              "type": "string",
              "example": "Kontoopplysinger"
            }
          },
          {
            "name": "environment",
            "in": "query",
            "description": "Filters on environment (\"test\", \"production\")",
            "required": true,
            "schema": {
              "type": "string",
              "example": "production"
            }
          },
          {
            "name": "orgNos",
            "in": "query",
            "description": "Filters on publishers' organization numbers",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "organization number"
              },
              "example": "974760673,974761076"
            }
          },
          {
            "name": "activeOnly",
            "in": "query",
            "description": "Filters on active or all endpoints",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true,
              "example": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EndpointsQueryResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "QueryResponse": {
        "type": "object",
        "properties": {
          "aggregations": {
            "$ref": "#/components/schemas/Aggregation"
          },
          "hits": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiSearchResult"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "EndpointsQueryResponse": {
        "type": "object",
        "properties": {
          "endpoints": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Endpoint"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "example": 1
          }
        }
      },
      "Aggregation": {
        "type": "object",
        "properties": {
          "formats": {
            "type": "object",
            "description": "A collection of formats and a count per format in query result",
            "properties": {
              "buckets": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AggregationBucket"
                }
              }
            }
          },
          "orgPath": {
            "type": "object",
            "description": "A organizational path and a count per level in query result",
            "properties": {
              "buckets": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AggregationBucket"
                }
              }
            }
          }
        }
      },
      "AggregationBucket": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "the item aggregated on"
          },
          "count": {
            "type": "number",
            "description": "the number of apis with the propertiy given key in the query result"
          }
        }
      },
      "ApiSearchResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The id given by the harvest system"
          },
          "title": {
            "type": "string",
            "description": "The title of the api, can be specified in multiple langauges [dct:title]"
          },
          "titleFormatted": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "description": "The description of the api, can be specified in multiple languages [dct:description]"
          },
          "descriptionFormatted": {
            "type": "string"
          },
          "formats": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "A list of formats returned by the api"
          },
          "publisher": {
            "$ref": "#/components/schemas/Publisher"
          },
          "nationalComponent": {
            "type": "boolean",
            "description": "Indication if the api is from an authoritative source (a National Component)"
          },
          "isOpenAccess": {
            "type": "boolean",
            "description": "Indication if the api has open access"
          },
          "isOpenLicense": {
            "type": "boolean",
            "description": "Indication if the api has open licence"
          },
          "isFree": {
            "type": "boolean",
            "description": "Indication if the api is free"
          },
          "statusCode": {
            "type": "string"
          },
          "deprecationInfoExpirationDate": {
            "type": "string"
          },
          "deprecationInfoReplacedWithUrl": {
            "type": "string"
          },
          "servers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Server"
            }
          }
        }
      },
      "Endpoint": {
        "type": "object",
        "properties": {
          "apiRef": {
            "type": "string",
            "description": "url to the the api-description in API-catalogue",
            "example": "https://fellesdatakatalog.brreg.no/apis/cb6483b8-4d94-473d-a4b9-8ee64abb9b91"
          },
          "orgNo": {
            "type": "string",
            "description": "The organization number to the publisher of the API",
            "example": 974760673
          },
          "serviceType": {
            "type": "string",
            "description": "The standard (\"type of service\") the API conforms to",
            "example": "Kontoopplysinger"
          },
          "url": {
            "type": "string",
            "description": "The Server Object url of the API",
            "example": "https://example.com/api/kontoopplysinger"
          },
          "activationDate": {
            "type": "string",
            "format": "date-time",
            "description": "The date-time from which the endpoint is active"
          },
          "expirationDate": {
            "type": "string",
            "format": "date-time",
            "description": "The date-time from which the endpoint is active"
          },
          "transportProfile": {
            "type": "string",
            "description": "transport method",
            "example": "kontoREST"
          },
          "environment": {
            "type": "string",
            "description": "The environment the url points to",
            "enum": [
              "test",
              "production"
            ]
          }
        }
      },
      "ApiDocument": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The id given by the harvest system"
          },
          "harvestSourceUri": {
            "type": "string",
            "description": "The source where the record was harvested from"
          },
          "apiSpecUrl": {
            "type": "string",
            "description": "The url of the specification which are used to harvest the specification"
          },
          "apiSpec": {
            "$ref": "#/components/schemas/ApiSpec"
          },
          "apiSpecification": {
            "$ref": "#/components/schemas/ApiSpecification"
          },
          "harvest": {
            "$ref": "#/components/schemas/Harvest"
          },
          "title": {
            "type": "string",
            "description": "The title of the api, can be specified in multiple langauges [dct:title]"
          },
          "description": {
            "type": "string",
            "description": "The description of the api, can be specified in multiple languages [dct:description]"
          },
          "formats": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "A list of formats returned by the api"
          },
          "publisher": {
            "$ref": "#/components/schemas/Publisher"
          },
          "contactPoint": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          },
          "datasetReference": {
            "type": "array",
            "description": "A list of references to the datasets that can be returned by the API",
            "items": {
              "$ref": "#/components/schemas/DatasetReference"
            }
          },
          "titleFormatted": {
            "type": "string"
          },
          "descriptionFormatted": {
            "type": "string"
          },
          "nationalComponent": {
            "type": "boolean",
            "description": "Indication if the api is from an authoritative source (a National Component)"
          },
          "isOpenAccess": {
            "type": "boolean",
            "description": "Indication if the api has open access"
          },
          "isOpenLicense": {
            "type": "boolean",
            "description": "Indication if the api has open licence"
          },
          "isFree": {
            "type": "boolean",
            "description": "Indication if the api is free"
          },
          "statusCode": {
            "type": "string"
          },
          "deprecationInfoExpirationDate": {
            "type": "string"
          },
          "deprecationInfoReplacedWithUrl": {
            "type": "string"
          }
        }
      },
      "ApiSpec": {
        "type": "object",
        "description": "Original API spec"
      },
      "ApiSpecification": {
        "type": "object",
        "description": "Parsed API specification",
        "properties": {
          "info": {
            "$ref": "#/components/schemas/Info"
          },
          "paths": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PathItem"
            }
          },
          "externalDocs": {
            "$ref": "#/components/schemas/ExternalDocumentation"
          },
          "formats": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A list of formats returned by the api"
            }
          }
        }
      },
      "Harvest": {
        "type": "object",
        "description": "Information about when the API was first and last harvested by the system"
      },
      "Publisher": {
        "type": "object",
        "description": "The publisher of the api [dct:publisher]",
        "properties": {
          "uri": {
            "type": "string",
            "description": "Link to the organization entry in The Brønnøysund Register Centre"
          },
          "id": {
            "type": "string",
            "description": "Organization number"
          },
          "name": {
            "type": "string",
            "description": "The name of the organization as given in the The Brønnøysund Register Centre"
          },
          "orgPath": {
            "type": "string"
          },
          "prefLabel": {
            "$ref": "#/components/schemas/PrefLabel"
          }
        }
      },
      "PrefLabel": {
        "type": "object",
        "properties": {
          "no": {
            "type": "string",
            "description": "The name of the publisher in Norwegian"
          }
        }
      },
      "Contact": {
        "type": "object",
        "description": "The contact point [dcat:contactPoint]",
        "properties": {
          "uri": {
            "type": "string"
          },
          "organizationName": {
            "type": "string"
          }
        }
      },
      "Info": {
        "type": "object",
        "description": "The Info Object"
      },
      "PathItem": {
        "type": "object",
        "description": "The Path Item Object"
      },
      "ExternalDocumentation": {
        "type": "object",
        "description": "The External Documentation Object"
      },
      "DatasetReference": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "uri": {
            "type": "string"
          },
          "title": {
            "type": "object",
            "properties": {
              "nb": {
                "type": "string",
                "description": "Title in Norwegian"
              }
            }
          }
        }
      },
      "Server": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      }
    }
  }
}