restapi

Overview ¶

Package restapi 🏹 Archer

# Documentation
Archer is an OpenStack-style API service that privately connects services across [OpenStack Networks](https://docs.openstack.org/neutron/latest/admin/intro-os-networking.html). Consumers pick a *service* from a catalog and **inject** it into their own network — the service becomes reachable through a private IP, without exposing either network to the other.

Archer integrates with *OpenStack Keystone* for authentication and *OpenStack Neutron* for network and port management.

### Concepts
Archer exposes two resource types:

* **Services** — private or public services registered in Archer. They are reached by creating an endpoint.
* **Endpoints** — IP endpoints in a local network that transparently forward to a service living in another private network.

### Features
* Multi-tenant via OpenStack Identity
* OpenStack `policy.json` access policies
* Prometheus exporter
* Rate limiting and CORS
* CADF-compatible audit trail
* Sentry error reporting
* OpenStack-style CLI client (`archerctl`)

### Supported Backends
* **F5 BigIP** — provisioned via the `archer-f5-agent`
* **Network Injection** — the `archer-ni-agent`, using HAProxy inside Linux network namespaces; works alongside `openvswitch-agent` or `linuxbridge-agent`

### Requirements
* PostgreSQL
* OpenStack Keystone
* OpenStack Neutron

## API properties
Archer exposes a RESTful HTTP API.

#### Request / Response format
Requests and responses use JSON. `POST` requests must set `Content-Type: application/json`; responses always come back with `Content-Type: application/json`.

#### Authentication
Archer uses OpenStack Keystone. Requests must include a Keystone token in the `X-Auth-Token` header. Because the project ID is derived from the token, `project_id` is not required on create requests.

#### Pagination
List operations return a bounded number of items. Navigate the collection with URI parameters:

```
?limit=100&marker=1234&page_reverse=False
```

* `marker` — the ID of the last item from the previous page
* `limit` — page size (clamped to the deployment maximum)
* `page_reverse` — reverse pagination direction

Responses include atom `next` and `previous` links. The final forward page has no `next`; the final reverse page has no `previous`. Deployments advertise pagination support through the `pagination` capability on the API detail endpoint.

#### Sorting
Use `sort` with a comma-separated list of keys, in priority order. Prefix a key with `-` to sort descending:

```
?sort=key1,-key2,key3
```

Sort support is advertised through the `sort` capability on the API detail endpoint.

#### Filtering by tags
Most resources (services, endpoints, …) accept tags. Archer supports four tag filters on list operations:

* `tags` — entities that have **all** the given tags
* `tags-any` — entities that have **any** of the given tags
* `not-tags` — entities that do **not** have all of the given tags
* `not-tags-any` — entities that do **not** have any of the given tags

Each tag is limited to 64 characters. Filters can be combined:

```
?tags=red,blue&tags-any=green,orange
```

#### Response Codes (Faults)

| Code  | Description       |
| ----- | ----------------- |
| 400   | Validation error |
| 401   | Unauthorized |
| 403   | Policy denies the action, or the project is over quota |
| 404   | Resource not found |
| 409   | Conflict |
| 422   | Unprocessable Entity |
| 429   | Rate limit exceeded |
| 500   | Internal server error |

## Endpoint identification

Archer supports the Proxy Protocol v2 for endpoint identification.

The Proxy Protocol is a widely used protocol for passing client connection information through a load balancer to the backend server. It is used to identify the original client IP address and port number. The Proxy Protocol v2 is a binary protocol that is more efficient than the original text-based Proxy Protocol v1.

The proxy protocol header also includes the ID of the endpoint. This information is encoded using a custom Type-Length-Value (TLV) vector as follows.

| Field | Length (Octets) | Description                                                    |
| ----- | --------------- | -------------------------------------------------------------- |
| Type  | 1               | PP2_TYPE_SAPCC (0xEC)                                          |
| Length| 2               | Length of the value (UUIDv4 is always 36 byte as ASCII string) |
| Value | 36              | ASCII UUID of the endpoint                                     |

Schemes:
  http
  https
Host: localhost
BasePath: /
Version: 2.7.1
License: Apache 2.0 https://www.apache.org/licenses/LICENSE-2.0.html
Contact: SAP SE / Converged Cloud https://sap.com

Consumes:
  - application/json

Produces:
  - application/json

swagger:meta