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.",
        "title": "Thamanyah Discovery API",
        "contact": {},
        "version": "1.0"
    },
    "basePath": "/",
    "paths": {
        "/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.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"
                }
            }
        }
    }
}