Northbound API Schema

The northbound API is based on the HTTP server-sent event extension.

Update Stream API

When every unicorn server starts and finishes its bootstrap, it will send a registration request to the orchestrator. And the orchestrator will know that a new unicorn server is ready. Then the orchestrator can start an update stream connection immediately by using the update stream API.

Request Example

GET /updates/ HTTP/1.1
Host: alto.example.com
Connection: keep-alive
Accept: text/event-stream

After sending the request, the orchestrator will return a URI for the related control stream API, keep the connection alive and wait for the unicorn server to send the query response from the SSE stream.

Response Example

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: text/event-stream

event: application/updatestreamcontrol
data: {"control-uri": "http://alto.example.com/updates/streams/2718281828459"}

... Waiting for the control operation from the control stream ...

event: application/json
data: {"query-id": 123, “response”: [ "172.18.0.3", "172.18.0.4" ]}

Control Stream API

The orchestrator can then send some control operations to the control-uri which is returned by the initial event of the update stream.

Request Example

POST /updates/ HTTP/1.1
Host: alto.example.com
Accept: text/event-stream,application/json
Content-Type: application/json

{
  "action": "add",
  "query-id": 123,
  "query-type": "path-query",
  "query-desc": [
        {
          "flow": {
            "flow-id": 20,
            "dstIP": "192.168.1.100",
            "srcIP": "192.168.2.100",
            "dstPort": 54321,
            "protocol": "tcp"
          },
          "ingress-point": ""
        },
        {
          "flow": {
           "flow-id": 10,
            "dstIP": "192.168.2.101",
            "srcIP": "192.168.3.101",
            "srcPort": 1234,
            "dstPort": 8080,
            "protocol": "tcp"
          },
          "ingress-point": "172.17.0.2"
        }
    ]
}

Request Schema

---
"$schema": http://json-schema.org/draft-06/schema#
properties:
  action:
    description: Action to manipulate queries
    examples:
    - add
    id: "/properties/action"
    title: The Action Schema.
    type: string
    enum
    - add
    - delete
    - merge
    - erase
    - new
  query-id:
    type: integer
    minimum: 0
    example: 1
  query-desc:
    items:
      properties:
        flow:
          properties:
            flow-id:
              description: The id of the flow
              examples:
              - 10
              type: integer
              minimum: 0
            src-ip:
              examples:
              - 192.168.2.100
              type: string
              pattern: ^((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5]))|$
            dst-ip:
              examples:
              - 192.168.1.100
              type: string
              pattern: ^((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5]))|$
            dst-port:
              examples:
              - '54321'
              type: integer
              minimum: 0
            protocol:
              default: tcp
              examples:
              - tcp
              type: string
              enum:
              - tcp
              - udp
              - sctp
          type: object
          required:
          - flow-id
        ingress-point:
          default: ''
          examples:
          - "10.0.1.1"
          type: string
          pattern: ^((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5]))|$
      type: object
      required:
      - flow
      - ingress-point
    type: array
  query-type:
    default: path-query
    type: string
    enum:
    - path-query
    - resource-query
type: object
required:
- action
- query-type

Response Example

The unicorn server will return whether the control operation is successful.

Besides the unicorn server will return the query_id if the request ask for adding a query.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "query-id": "123456789",
    "meta": {
        "code": "success"
    }
}