Tenant API

Meniscus API: v1

Overview

Meniscus provides a RESTful HTTP-based API for modifying tenants and their associated resources.

Media Types

The API supports application/json encoded as UTF-8.

API Versioning

See the Versioning API

API Elements

Tenants: A Tenant represents a user and is the parent element for Tokens and Event Producers. A tenant lives in isolation from all other tenants. All child elements of a tenant can only have relationships with other elements that belong to the same tenant.

Token: A Token is a security token to authenticate log submissions into the system

Event Producers: An Event Producer is any application or service that produces events that will feed into the system. Event Producer definitions may be reused across profiles.

Using the Tenant API

Tenants

Create a Tenant

Template

*indicates required field

POST {host_url}/{version}
{
    "tenant": {
        "tenant_id": "{tenant_id}*"
    }
}

Request

POST /v1 HTTP/1.1
Host: meniscus.example.com

{
    "tenant": {
        "tenant_id": "1022"
    }
}

Response

Note that the location of the newly created tenant is returned in the response.

Status: 201 Created
Location: /v1/1022

Get a Tenant

This example will show how to retrieve the tenant created in the previous example.

Template

GET {host_url}/{version}/{tenant_id}

Request

GET /v1/1022 HTTP/1.1
Host: meniscus.example.com

Response

{
    "tenant": {
        "tenant_id": "1022",
        "tenant_name": "datacenter_application"
        "event_producers": [],
	"token": {
	  	"valid": {uuid4},
		"previous": nil
		"last_changed": {current timestamp}
	}
    }
}

Tokens

Validate a Token

Template

HEAD /v1/{tenant_id}/token HTTP/1.1

Request

HEAD /v1/e69682ac-8b70-402e-8c4c-d8ef5da653ba/token HTTP/1.1
MESSAGE-TOKEN: c7ceac21-8022-4c57-a6c9-fef8bbec6a17

Response if the token is valid

HTTP/1.1 200 OK

Response if the token is not valid

HTTP/1.1 400 BAD REQUEST

Resetting a Token (default)

Template

POST /{version}/{tenant_id}/token HTTP/1.1

Request

POST /v1/89c38542-0c78-41f1-bcd2-5226189ccab9/token HTTP/1.1

Response

HTTP/1.1 203 NON-AUTHORITATIVE INFORMATION
LOCATION: /{version}/{tenant_id}/token

Resetting a Token (immediate)

Template

POST /{version}/{tenant_id}/token HTTP/1.1

{
	"token": {
		"invalidate_now": true
	}
}

Request

POST /v1/89c38542-0c78-41f1-bcd2-5226189ccab9/token HTTP/1.1

{
	"token": {
		"invalidate_now": true
	}
}

Response

HTTP/1.1 203 NON-AUTHORITATIVE INFORMATION
LOCATION: /{version}/{tenant_id}/token

Event Producers

Event Producers represent sources of events that will be feeding into Meniscus. Event Producers require a name and a pattern (event format) to be specified. There are optional parameters that specify whether events from the producer should be durable or encrypted. If these fields are not specified in the POST, they will default to FALSE.

Create an Event Producer

Template

*indicates required field

POST {host_url}/{version}/{tenant_id}/producers
{
    "event_producer": {
        "name": "{name}*",
        "pattern": "{pattern}*",
        "durable": {true|false},
        "encrypted": {true|false},
        "sinks": ["{sinks}"]
    }
}

Request

POST /v1/1022/producers HTTP/1.1
Host: meniscus.example.com

{
    "event_producer": {
        "name": "mybillingapp",
        "pattern": "syslog",
        "durable": true,
        "encrypted": false,
        "sinks": ["elasticsearch"]
    }
}

Response

Note that the location of the newly created event producer is returned in the response.

Status: 201 Created
Location: /v1/1022/producers/1

Get all Event Producers for a Tenant

Template

GET {host_url}/{version}/{tenant_id}/producers

Request

GET /v1/1022/producers HTTP/1.1
Host: meniscus.example.com

Response

Note that this example has 2 event producers returned for the specified tenant

Status: 200 OK
{
	"event_producers": [
		{
			"pattern": "syslog",
			"durable": false,
			"encrypted": false,
                        "sinks": ["elasticsearch"],
			"id": 1,
			"name": "mybillingapp"
		},
		{
			"pattern": "syslog",
			"durable": false,
			"encrypted": false,
                        "sinks": ["elasticsearch", "hdfs"],
			"id": 2,
			"name": "myauthenticationapp"
		}
	]
}

Get Event Producer

Retrieve a specific event producer.

Template

GET {host_url}/{version}/{tenant_id}/producers/{producer_id}

Request

GET /v1/1022/producers/2 HTTP/1.1
Host: meniscus.example.com

Response

Status: 200 OK
{
	"event_producer": {
		"pattern": "syslog",
		"durable": false,
		"encrypted": false,
                "sinks": ["elasticsearch"],
		"id": 2,
		"name": "mybillingapp"
	}
}

Update Event Producer

Update a specified event producer. When updating an event producer the API the caller may include all fields or only the fields to be updated.

Template

PUT {host_url}/{version}/{tenant_id}/producers/{producer_id}
{
    "event_producer": {
        "name": "{name}*",
        "pattern": "{pattern}*",
        "durable": {true|false},
        "encrypted": {true|false},
        "sinks": ["{sinks}"]
    }
}

Request

PUT /v1/1022/producers/2 HTTP/1.1
Host: meniscus.example.com
{
    "event_producer": {
        "name": "mybillingapp",
        "pattern": "syslog",
        "durable": true,
        "encrypted": false,
        "sinks": ["elasticsearch"]
    }
}

Response

Status: 200 OK

Delete Event Producer

Delete a specified event producer.

Template

DELETE {host_url}/{version}/{tenant_id}/producers/{producer_id}

Request

DELETE /v1/1022/producers/2 HTTP/1.1
Host: meniscus.example.com

Response

Status: 200 OK