peer-matchmaking.yaml

swagger: '2.0'
info:
  title: Peer Matchmaking API
  description: Analyse your traffic to find beneficial peering agreements.
  version: "1.0.0"
host: api.example.org
schemes:
  - https
basePath: /v1
produces:
  - application/json
paths:
  /graph:
    get:
      summary: Peering Graph
      description: |
        The Peering Graph endpoint returns peering data as a list of interconnected
        nodes.
      produces:
        - application/json
      responses:
        200:
          description: An array of nodes.
          schema:
            type: array
            items:
              $ref: '#/definitions/Node'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /toptalkers/{n}:
    get:
      summary: Top Talkers
      description: |
        The Top Talkers endpoint returns a list of edges with the largest amount of
        traffic exchanged with the source.
      parameters:
        - name: n
          in: path
          description: Top N talkers to output.
          required: true
          type: integer
          format: int32
          default: 10
          minimum: 1
          maximum: 100
      responses:
        200:
          description: An array of graph edges with traffic values.
          schema:
            type: array
            items:
              $ref: '#/definitions/Edge'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /route:
    post:
      summary: Build Route
      description: |
        Checks if a peering agreement can be established between the source and
        the destination IP addresses and returns a list of edges to redraw,
        including the edges between source and destination, and the edges
        where line width has to be changed.
      parameters:
        - name: source
          in: formData
          description: Source IP address.
          required: true
          type: string
          format: cidr
        - name: destination
          in: formData
          description: Source IP address.
          required: true
          type: string
          format: cidr
      responses:
        200:
          description: An array of graph edges with traffic values to redraw.
          schema:
            type: array
            items:
              $ref: '#/definitions/Edge'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
definitions:
  Node:
    type: object
    required:
      - id
      - type
    properties:
      id:
        type: integer
        format: int32
      type:
        type: string
        enum:
          - node
          - isp
          - ixp
      label:
        type: string
      peering:
        type: array
        items:
          type: integer
          format: int32
      source:
        type: boolean
  Edge:
    type: object
    required:
      - pair
      - traffic
    properties:
      pair:
        type: array
        items:
          type: integer
          format: int32
      traffic:
        type: integer
        format: int32
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string