swagger.json

{
    "swagger": "2.0",
    "info": {
        "description": "This document describes the Amalgam8 Service Registry API.",
        "version": "1.0.0",
        "title": "Amalgam8 Service Registry REST API",
        "termsOfService": "http://swagger.io/terms/"
    },
    "basePath": "/",
    "schemes": [
        "https",
        "http"
    ],
    "consumes": [
        "application/json"
    ],
    "produces": [
        "application/json"
    ],
    "securityDefinitions": {
        "tokenAuth": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header",
            "description": "APIKEY Authentication. Works over `HTTP(S)`. Required for namespace authorization."
        }
    },
    "paths": {
        "/api/v1/services": {
            "get": {
                "summary": "List of services",
                "description": "Returns a list of all registered services",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "security": [
                    {
                        "tokenAuth": []
                    }
                ],
                "tags": [
                    "Services"
                ],
                "responses": {
                    "200": {
                        "description": "A list of registered services",
                        "schema": {
                            "$ref": "#/definitions/Services"
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "401": {
                        "description": "Unauthorized. The token is not valid.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "default": {
                        "description": "Unexpected error",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        },
        "/api/v1/services/{service_name}": {
            "get": {
                "deprecated": true,
                "summary": "List of instances",
                "description": "Returns a list of all registered instances for service named {service_name}",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "security": [
                    {
                        "tokenAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "service_name",
                        "in": "path",
                        "description": "Service name",
                        "type": "string",
                        "required": true
                    }
                ],
                "tags": [
                    "Services"
                ],
                "responses": {
                    "200": {
                        "description": "A service object with a list of registered instances",
                        "schema": {
                            "$ref": "#/definitions/Service"
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "401": {
                        "description": "Unauthorized. The token is not valid.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "404": {
                        "description": "The service name does not exist",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "default": {
                        "description": "Unexpected error",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        },
        "/api/v1/instances": {
            "post": {
                "summary": "Register a service instance",
                "description": "Register a new service instance",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "security": [
                    {
                        "tokenAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "instance",
                        "in": "body",
                        "description": "instance registration information",
                        "schema": {
                            "$ref": "#/definitions/Instance"
                        },
                        "required": true
                    }
                ],
                "tags": [
                    "Instances"
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "headers": {
                            "Location": {
                                "type": "string",
                                "description": "URL of the registered instance"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/Registration"
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "401": {
                        "description": "Unauthorized. The token is not valid",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "default": {
                        "description": "Unexpected error",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            },
            "get": {
                "summary": "List of instances",
                "description": "Returns a list of registered service instances",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "security": [
                    {
                        "tokenAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "fields",
                        "in": "query",
                        "description": "Comma separated list of instance fields to include in the response. If the parameter is missing, all fields are returned",
                        "type": "string",
                        "required": false
                    },
                    {
                        "name": "tags",
                        "in": "query",
                        "description": "Comma separated list of tags of the instances. Only instances matching all tags are returned",
                        "type": "string",
                        "required": false
                    },
                    {
                        "name": "service_name",
                        "in": "query",
                        "description": "Service name of the instances",
                        "type": "string",
                        "required": false
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "description": "Status of the instances",
                        "type": "string",
                        "required": false
                    }
                ],
                "tags": [
                    "Instances"
                ],
                "responses": {
                    "200": {
                        "description": "An Instances object with a list of registered instances",
                        "schema": {
                            "$ref": "#/definitions/Instances"
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "401": {
                        "description": "Unauthorized. The token is not valid",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "default": {
                        "description": "Unexpected error",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        },
        "/api/v1/instances/{id}": {
            "delete": {
                "summary": "De-register a service instance",
                "description": "Removes the registration for an existing service instance",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "security": [
                    {
                        "tokenAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "instance identifier",
                        "type": "string",
                        "required": true
                    }
                ],
                "tags": [
                    "Instances"
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "400": {
                        "description": "Bad request",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "401": {
                        "description": "Unauthorized. The token is not valid",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "410": {
                        "description": "The instance does not exist",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "default": {
                        "description": "Unexpected error",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        },
        "/api/v1/instances/{id}/heartbeat": {
            "put": {
                "summary": "Renew an existing service instance registration",
                "description": "Sends a heartbeat for an existing service instance registration. Failing to renew the registration will result in the instance being removed from the registry.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "security": [
                    {
                        "tokenAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "instance identifier",
                        "type": "string",
                        "required": true
                    }
                ],
                "tags": [
                    "Instances"
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "400": {
                        "description": "Bad request",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "401": {
                        "description": "Unauthorized. The token is not valid",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "410": {
                        "description": "The instance does not exist",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "default": {
                        "description": "Unexpected error",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "Endpoint": {
            "properties": {
                "type": {
                    "type": "string",
                    "description": "Endpoint type: 'udp', 'tcp', 'http', 'https',  or 'user'."
                },
                "value": {
                    "type": "string",
                    "description": "Endpoint value, formatted according to the defined type (e.g., host[:port] for 'tcp')."
                }
            }
        },
        "Instance": {
            "properties": {
                "service_name": {
                    "type": "string"
                },
                "endpoint": {
                    "$ref": "#/definitions/Endpoint"
                },
                "ttl": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Client's requested time to live, measured in seconds. The value may be overriden by the server."
                },
                "status": {
                    "type": "string",
                    "description": "Status of the instance"
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "Optional array of tags to associate with the instance"
                },
                "metadata": {
                    "description": "Optional user metadata. The value can be null, a primitive, an array or an arbitrary object"
                }
            }
        },
        "Instances": {
            "properties": {
                "instances": {
                    "type": "array",
                    "description": "Array of instances",
                    "items": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "Instance identifier (opaque)"
                            },
                            "service_name": {
                                "type": "string",
                                "description": "Service name"
                            },
                            "endpoint": {
                                "$ref": "#/definitions/Endpoint"
                            },
                            "ttl": {
                                "type": "integer",
                                "format": "int64",
                                "description": "Time to live measured in seconds"
                            },
                            "status": {
                                "type": "string",
                                "description": "Status of the instance"
                            },
                            "tags": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                },
                                "description": "Optional array of tags associated with the instance"
                            },
                            "metadata": {
                                "description": "Optional metadata, as set in instance registration"
                            },
                            "last_heartbeat": {
                                "type": "string",
                                "format": "date-time",
                                "description": "Last heartbeat time"
                            }
                        }
                    }
                }
            }
        },
        "Service": {
            "properties": {
                "service_name": {
                    "type": "string",
                    "description": "Unique identifier representing the service name. For example, mysql, database or frontend."
                },
                "instances": {
                    "type": "array",
                    "description": "Array of instances",
                    "items": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "Instance identifier (opaque)"
                            },
                            "endpoint": {
                                "$ref": "#/definitions/Endpoint"
                            },
                            "ttl": {
                                "type": "integer",
                                "format": "int64",
                                "description": "Time to live measured in seconds"
                            },
                            "status": {
                                "type": "string",
                                "description": "Status of the instance"
                            },
                            "tags": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                },
                                "description": "Optional array of tags associated with the instance"
                            },
                            "metadata": {
                                "description": "Optional metadata, as set in instance registration"
                            },
                            "last_heartbeat": {
                                "type": "string",
                                "format": "date-time",
                                "description": "Last heartbeat time"
                            }
                        }
                    }
                }
            }
        },
        "Services": {
            "properties": {
                "services": {
                    "type": "array",
                    "description": "Array of services",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "Registration": {
            "properties": {
                "id": {
                    "type": "string",
                    "description": "Instance identifier (opaque)"
                },
                "ttl": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Time to live measured in seconds"
                },
                "links": {
                    "type": "object",
                    "properties": {
                        "self": {
                            "type": "string",
                            "description": "URL of this instance"
                        },
                        "heartbeat": {
                            "type": "string",
                            "description": "URL to use for sending heartbeats on behalf of this instance"
                        }
                    }
                }
            }
        },
        "Error": {
            "properties": {
                "error": {
                    "type": "string"
                }
            }
        }
    }
}