notifications-api/app/spec/rest.py

from flask import jsonify, Blueprint
from apispec import APISpec


spec = Blueprint('spec', __name__)


api_spec = APISpec(
    title='GOV.UK Notify',
    version='0.0.0'
)

api_spec.definition('NotificationWithTemplateSchema', properties={
    "billable_units": {
        "format": "int32",
        "type": "integer"
    },
    "created_at": {
        "format": "date-time",
        "type": "string"
    },
    "id": {
        "format": "uuid",
        "type": "string"
    },
    "job": {
        "properties": {
            "id": {
                "format": "uuid",
                "type": "string"
            },
            "original_file_name": {
                "type": "string"
            }
        },
        "required": [
            "id",
            "original_file_name"
        ],
        "type": "object"
    },
    "job_row_number": {
        "format": "int32",
        "type": "integer"
    },
    "reference": {
        "type": "string"
    },
    "sent_at": {
        "format": "date-time",
        "type": "string"
    },
    "sent_by": {
        "type": "string"
    },
    "service": {
        "type": "string"
    },
    "status": {
        "enum": [
            "delivered",
            "sending",
            "technical-failure",
            "temporary-failure",
            "permanent-failure",
            "pending",
            "failed"
        ],
        "type": "string"
    },
    "template": {
        "properties": {
            "id": {
                "format": "uuid",
                "type": "string"
            },
            "name": {
                "type": "string"
            },
            "template_type": {
                "enum": [
                    "sms",
                    "email",
                    "letter"
                ],
                "type": "string"
            }
        },
        "required": [
            "template_type",
            "name"
        ],
        "type": "object"
    },
    "template_version": {
        "format": "int32",
        "type": "integer"
    },
    "to": {
        "type": "string"
    },
    "updated_at": {
        "format": "date-time",
        "type": "string"
    }
})
api_spec.definition('NotificationSchema', properties={
    "notification": {
        "$ref": "#/definitions/NotificationWithTemplateSchema"
    }
})
api_spec.definition('NotificationsSchema', properties={
    "notifications": {
        "type": "array",
        "items": {
            "$ref": "#/definitions/NotificationWithTemplateSchema"
        }
    }
})
api_spec.definition('NotificationSentSchema', properties={
    "body": {
        "description": "The content of the message",
        "type": "string"
    },
    "notification": {
        "properties": {
            "id": {
                "type": "string"
            }
        },
        "type": "object"
    },
    "subject": {
        "description": "The subject of the email (present for email notifications only)",
        "type": "string"
    },
    "template_version": {
        "description": "The version number of the template that was used",
        "type": "integer"
    }
})
api_spec.definition('Error', properties={
    'result': {
        'type': 'string',
        'description': 'will say ‘error’'
    },
    'message': {
        'type': 'string',
        'description': 'description of the error'
    }
})
api_spec.add_path(path="/notifications", operations={
    "get": {
        "parameters": [
            {
                "description": "page number",
                "in": "query",
                "name": "page",
                "type": "integer"
            },
            {
                "default": 50,
                "description": "number of notifications per page",
                "in": "query",
                "name": "page_size",
                "type": "integer"
            },
            {
                "default": 7,
                "description": "number of days",
                "in": "query",
                "name": "limit_days",
                "type": "integer"
            },
            {
                "description": "sms or email",
                "enum": [
                    "sms",
                    "email"
                ],
                "in": "query",
                "name": "template_type",
                "type": "string"
            },
            {
                "description": "sms or email",
                "in": "query",
                "name": "status",
                "type": "string"
            }
        ],
        "responses": {
            "200": {
                "description": "Notifications found",
                "schema": {
                    "$ref": "#/definitions/NotificationsSchema"
                }
            },
            "400": {
                "description": "Bad request",
                "schema": {
                    "$ref": "#/definitions/Error"
                }
            },
            "401": {
                "description": "Authorisation header is missing",
                "schema": {
                    "$ref": "#/definitions/Error"
                }
            },
            "403": {
                "description": "Invalid or expired token",
                "schema": {
                    "$ref": "#/definitions/Error"
                }
            },
            "404": {
                "description": "No notifications found"
            }
        }
    }
})
api_spec.add_path(path="/notification/{notification_id_or_type}", operations={
    "get": {
        "parameters": [
            {
                "description": "16 character UUID",
                "in": "path",
                "name": "notification_id_or_type",
                "required": True,
                "type": "string"
            }
        ],
        "responses": {
            "200": {
                "description": "Found",
                "schema": {
                    "$ref": "#/definitions/NotificationSchema"
                }
            },
            "401": {
                "description": "Authorisation header is missing",
                "schema": {
                    "$ref": "#/definitions/Error"
                }
            },
            "403": {
                "description": "Invalid or expired token",
                "schema": {
                    "$ref": "#/definitions/Error"
                }
            },
            "404": {
                "description": "Not found"
            }
        }
    },
    "post": {
        "description": "Send a single email or text message",
        "parameters": [
            {
                "description": "email or sms",
                "in": "path",
                "name": "notification_id_or_type",
                "pattern": "[email|sms]",
                "required": True,
                "type": "string"
            },
            {
                "description": "the recipient's phone number or email address",
                "in": "formData",
                "name": "to",
                "required": True,
                "type": "string"
            },
            {
                "description": "the ID of the template to use",
                "in": "formData",
                "name": "template",
                "required": True,
                "type": "string"
            },
            {
                "description": "specifies the placeholders and values in your templates",
                "in": "formData",
                "name": "personalisation",
                "type": "string"
            }
        ],
        "responses": {
            "200": {
                "description": "Notification sent",
                "schema": {
                    "$ref": "#/definitions/NotificationSentSchema"
                }
            },
            "400": {
                "description": "Bad request",
                "schema": {
                    "$ref": "#/definitions/Error"
                }
            },
            "401": {
                "description": "Authorisation header is missing",
                "schema": {
                    "$ref": "#/definitions/Error"
                }
            },
            "403": {
                "description": "Invalid or expired token",
                "schema": {
                    "$ref": "#/definitions/Error"
                }
            },
            "429": {
                "description": "You have reached the maximum number of messages you can send per day",
                "schema": {
                    "$ref": "#/definitions/Error"
                }
            }
        }
    }
})


@spec.route('')
def get_spec():
    return jsonify(api_spec.to_dict())