[[enmasse-resource-definition]]
= EnMasse resource definition

This document defines the resources consumed and produced by APIs and
can be considered a base for writing the schema for the data formats.
The link:model.adoc[address model] defines address spaces and addresses
which translates to these resources.

The resources defined here may be created, deleted and updated through
different APIs. Either the Open Service Broker API, the custom HTTP API,
or using AMQP management.

The resources are defined in the JSON format.

[[addressspace]]
== AddressSpace

[options="header"]
|=======================================================================
|Method |Path |Description
|GET |/v1/addressspaces |to retrieve list

|GET |/v1/addressspaces/myspace |to retrieve single address space

|POST |/v1/addressspaces |create and append single or multiple
(AddressSpace, or AddressSpaceList) or fail if exists

|PUT |/v1/addressspaces |replace a single or multiple (AddressSpace, or
AddressSpaceList)

|PUT |/v1/addressspaces/:name |create or replace

|DELETE |/v1/addressspace/:name |delete
|=======================================================================

The `AddressSpace` resource defines the type of address space and
endpoint for connecting.

[source,javascript]
....
{
    "apiVersion": "enmasse.io/v1",
    "kind": "AddressSpace",
    "metadata": {
        "name": "myspace", // Required
        "namespace": "mynamespace" // Optional
    },
    "spec": {
        "type": "standard", // Required. Default is 'standard', potentially configurable
        "plan": "small", // Required. This is the aggregate 'size' of the address space (i.e. controls how
                         // many addresses and how many resources each address may consume

        "endpoints": [ // Optional. If not provided, the default generated hostnames will be provided. 
            {
                "name": "endpoint1",             // Required.
                "service": "messaging",          // Required. 
                "host": "messaging.example.com", // Optional. The host name for this endpoint to use for routing by the load balancer
                "cert": {                        // Optional. Self-signed certificates are generated if not specified
                    "provider": "selfSigned",    // Provider may be selfsigned or 'wildcard'
                    "secretName": "mysecret"
                }
            }
        }
    }
}
....

[[addressspacelist]]
=== AddressSpaceList

[source,javascript]
....
{
    "apiVersion": "enmasse.io/v1", // Required
    "kind": "AddressSpaceList", // Required
    "items": [
        {
            ...
        }
    ]
}
....

[[address]]
== Address

[options="header"]
|=======================================================================
|Method |Path |Description
|GET |/v1/addresses/myspace |to retrieve list

|GET |/v1/addresses/myspace/:name |to retrieve single address

|POST |/v1/addresses/myspace |create and append single or multiple
(Address, or AddressList) or fail if exists

|PUT |/v1/addresses/myspace/:name |replace a single address

|PUT |/v1/addresses/myspace |replace multiple addresses

|DELETE |/v1/addresses/myspace/:name |delete

|DELETE |/v1/addresses/myspace |delete all
|=======================================================================

The `Address` resource defines an address and its semantics.

TODO: Figure out where to put a user-specified description of the
address

[source,javascript]
....
{
    "apiVersion": "enmasse.io/v1", // Required
    "kind": "Address", // Required
    "metadata": {
        "name": "myqueue", // optional, assigned by API. Default would be set to 'myqueue-4bfe49c2-60b5-11e7-a5d0-507b9def37d9'
        "uuid": "4bfe49c2-60b5-11e7-a5d0-507b9def37d9", // Optional, assigned by API
        "addressSpace": "myspace" // Optional. Defaults to 'default' address space
    },
    "spec": {
        "address": "my_queue",  // Required. Default is .metadata.name
        "type": "queue",        // Required. Valid types are defined by the AddressSpace
        "plan": "medium"        // Required. Valid plans can be found using /apis/enmasse.io/v1/schema
    }
}
....

[[addresslist]]
=== AddressList

[source,javascript]
....
{
    "apiVersion": "enmasse.io/v1", // Required
    "kind": "AddressList", // Required
    "metadata": {
        "addressSpace": "myspace" // Optional. Defaults to 'default' address space
    },
    "items": [
        {
            ...
        }
    ]
}
....

GET /v1/schema

[source,json]
....
{
    "apiVersion": "enmasse.io/v1",
    "kind": "Schema",
    "spec": {
        "addressSpaceTypes": [
            {
                "name": "standard",
                "addressTypes": [
                    {
                        "name": "queue",
                        "description": "Queue is cool",
                        "plans": [
                            {
                                "name": "myplan",
                                "description": "Is great"
                            }
                        ]
                    }
                ],
                "plans": [
                    {
                        "name": "myplan",
                        "description": "Is great"
                    }
                ]
            }
        ]
    }
}
....

[[configserv]]
== Configserv

Configserv has been removed
