thamanyah/discovery/docs/swagger.json

{
    "swagger": "2.0",
    "info": {
        "description": "JSON API for browsing the Thamanyah catalogue. Read-side counterpart to the CMS, which is what ingests videos.\n\nThe catalogue search is `GET /api/videos`, listed below: title is matched lexically with the last word as a prefix, categories narrow to videos filed under any one of them, limit defaults to 20 and is capped at 100, and cursor is the opaque `nextCursor` of a previous search.",
        "title": "Thamanyah Discovery API",
        "contact": {},
        "version": "1.0"
    },
    "basePath": "/",
    "paths": {
        "/api/videos": {
            "get": {
                "description": "Finds catalogued videos by the words of their title and the categories they are filed under, most relevant first. Every parameter is optional — a request with none of them browses the whole catalogue, newest first. Paging is by cursor rather than by offset, so a page stays the same page while videos are being announced into the catalogue around it.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "videos"
                ],
                "summary": "Search the catalogue",
                "parameters": [
                    {
                        "type": "string",
                        "example": "desert fal",
                        "description": "Matched lexically against video titles: the words are all required, and the last is treated as a prefix so a part-typed word still finds something.",
                        "name": "title",
                        "in": "query"
                    },
                    {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "collectionFormat": "multi",
                        "example": "documentary",
                        "description": "Narrows the search to videos filed under any one of these names — not all of them. Repeat the parameter per category. Omitted means every category.",
                        "name": "categories",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "default": 20,
                        "description": "How many videos to return. Absent, zero or negative takes the default of 20; anything above the maximum of 100 is capped to it rather than refused, and the cursor still reaches the rest.",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Asks for the page after the one a previous search ended at. Send back the nextCursor from that search unchanged; it is opaque, and the only thing to do with it is return it.",
                        "name": "cursor",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/api.SearchResults"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/api.ProblemDetails"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/api.ProblemDetails"
                        }
                    }
                }
            }
        },
        "/api/videos/{id}": {
            "get": {
                "description": "Returns the catalogue's copy of a video: what a reader needs to show and play it. A video appears here only after the CMS has announced it as ready, so a video that is still transcoding — or one the CMS never made ready — is a 404.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "videos"
                ],
                "summary": "Get a catalogued video",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Video id, as issued by the CMS",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/api.Video"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/api.ProblemDetails"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/api.ProblemDetails"
                        }
                    }
                }
            }
        },
        "/health": {
            "get": {
                "description": "Reports that the service is up and serving. Used as the ALB target group health check; it does not verify the database connection.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "system"
                ],
                "summary": "Health check",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/api.HealthResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "api.HealthResponse": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "example": "ok"
                }
            }
        },
        "api.ProblemDetails": {
            "type": "object",
            "properties": {
                "detail": {
                    "type": "string",
                    "example": "The catalogue could not be read from the database. This is a server-side fault and the request was not processed; retrying in a few moments may succeed."
                },
                "status": {
                    "type": "integer",
                    "example": 500
                },
                "title": {
                    "type": "string",
                    "example": "Something Went Wrong Loading The Catalogue"
                },
                "type": {
                    "type": "string",
                    "example": "about:blank"
                }
            }
        },
        "api.SearchResults": {
            "type": "object",
            "properties": {
                "nextCursor": {
                    "description": "NextCursor reaches the page after this one. Empty on the last page,\nwhich is how a reader knows there is no more to ask for.",
                    "type": "string"
                },
                "videos": {
                    "description": "Videos are the matches, most relevant first. Never null: a search that\nmatches nothing is an empty list.",
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/api.Video"
                    }
                }
            }
        },
        "api.Video": {
            "type": "object",
            "properties": {
                "categories": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "documentary",
                        "news"
                    ]
                },
                "id": {
                    "type": "string",
                    "example": "0f8fad5b-d9cb-469f-a165-70867728950e"
                },
                "playbackUrl": {
                    "type": "string",
                    "example": "https://d111111abcdef8.cloudfront.net/videos/abc123/index.m3u8"
                },
                "title": {
                    "type": "string",
                    "example": "The Evening Bulletin"
                }
            }
        }
    }
}