ctan-openapi
Version:
OpenAPI descriptions for the CTAN API
213 lines • 7.24 kB
JSON
{
"openapi": "3.1.0",
"info": {
"title": "Querying the CTAN Database with JSON",
"description": "The CTAN provides mean to access the database and retrieve the information in form of JSON responses. Several entities can be queried.\n\nThe queries can be sent to the portal in form of a HTTP `GET` or `POST` request with some parameters. The response has the JSON as body. The request URL and parameters as well as the response are described on the detail section.",
"version": "2.0"
},
"servers": [
{
"url": "https://ctan.org"
}
],
"paths": {
"/search/json": {
"get": {
"summary": "Searching",
"description": "The search functionality can be used programmatically.",
"parameters": [
{
"name": "phrase",
"in": "query",
"description": "The search phrase, i.e. the words or search expressions to query for.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "offset",
"in": "query",
"description": "The offset for paging. The accompanying parameter `max` contains the page size. This parameter contains the first hit to be returned. If a negative number is passed in then it is replaced by `0`. If the offset is larger than the number of actual hits then the list of hits will be empty.",
"schema": {
"type": "integer",
"minimum": 0
}
},
{
"name": "max",
"in": "query",
"description": "The number of hits maximally returned. Larger values will be reduced to `256`. Lower values will be replaced by the default value.",
"schema": {
"type": "integer",
"default": 16,
"maximum": 256,
"minimum": 1
}
},
{
"name": "ext",
"in": "query",
"description": "Whether the sections are requested explicitly. If the value is `false` then all default sections are searched. Otherwise the sections to be searched have to be specified with additional parameters.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "PKG",
"in": "query",
"description": "Whether the package section should be included into the search. The package section contains the text fields of a package entry in the Catalogue.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "AUTHORS",
"in": "query",
"description": "Whether the author section should be included into the search. The author section contains the names of the contributors in the Catalogue.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "TOPICS",
"in": "query",
"description": "Whether the topics section should be included into the search. The topics section contains the text fields of the topics in the Catalogue.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "FILES",
"in": "query",
"description": "UNDOCUMENTED.\n\nWhether the file name in TeX archive should be included into the search.",
"schema": {
"type": "boolean",
"default": false
},
"$comment": "Used in the search form of the CTAN web page."
},
{
"name": "PORTAL",
"in": "query",
"description": "Whether the portal section should be included into the search. The portal section contains the text of the portal pages.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "wildcard",
"in": "query",
"description": "UNDOCUMENTED.\n\nEnable prefix search.",
"schema": {
"type": "boolean",
"default": false
},
"$comment": "Used in the search form of the CTAN web page."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResult"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"externalDocs": {
"url": "https://ctan.org/help/json/2.0/searching"
}
}
}
},
"components": {
"schemas": {
"SearchHit": {
"description": "Search hit.",
"type": "object",
"properties": {
"title": {
"description": "The page title of the hit.",
"type": "string"
},
"path": {
"description": "The absolute path on the CTAN Portal of the hit.",
"type": "string"
},
"text": {
"description": "Some additional text to display.",
"type": "string"
}
},
"required": [
"title",
"path",
"text"
],
"title": "SearchHit"
},
"SearchResult": {
"description": "Search result.",
"type": "object",
"properties": {
"numberOfHits": {
"description": "The total number of hits found.",
"type": "integer",
"minimum": 0
},
"offset": {
"description": "The offset at which the hits start. It is a repetition of the input argument `offset` which might have been adapted.",
"type": "integer",
"minimum": 0
},
"max": {
"description": "The maximal number of hits in this junk. It is a repetition of the input argument `max` which might have been adapted.",
"type": "integer",
"maximum": 256,
"minimum": 1
},
"phrase": {
"description": "The search phrase. It is a repetition of the input argument `phrase` which might have been adapted.",
"type": "string"
},
"hits": {
"description": "The list of hits in this junk.",
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchHit"
}
}
},
"required": [
"numberOfHits",
"offset",
"max",
"phrase",
"hits"
],
"title": "SearchResult"
}
},
"responses": {
"Error": {
"description": "The body of the response contains more or less meaningless text.",
"summary": "Error"
}
}
},
"externalDocs": {
"url": "https://ctan.org/help/json/2.0"
}
}