Skip to content

Instantly share code, notes, and snippets.

@jasikpark

jasikpark/bleck

Last active January 26, 2023 18:04
Show Gist options
  • Save jasikpark/d649b333ecafc98ae9822271008060a6 to your computer and use it in GitHub Desktop.
Save jasikpark/d649b333ecafc98ae9822271008060a6 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
bleck
openapi: 3.1.0
servers:
- url: https://api.defined.net
description: Default server
info:
description: |
# Introduction
This API is documented in **OpenAPI format** and describes methods that can be invoked when using an api key from <https://admin.defined.net/settings/api-keys>
Each endpoint is versioned individually, under a `/vXX` endpoint, ex `/v1/hosts` would become `/v2/hosts` with a breaking change, while `/v1/host-and-enrollment-code` would remain at `/v1`
<SecurityDefinitions />
version: 0.0.1
title: Defined Networking API Docs
termsOfService: http://defined.net/terms/
contact:
name: API Support
url: https://www.defined.net/contact?reason=Support
x-logo:
url: https://docs.defined.net/img/logo.svg
altText: Defined Networking logo
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
description: Find more about the API here
url: https://docs.defined.net/guides/automating-host-creation/
tags:
- name: hosts
description: Operations requiring `host:*` scope
paths:
/v1/host-and-enrollment-code:
get:
summary: Create a host and enrollment code
operationId: createHostandGetEnrollmentCode
tags:
- hosts
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Name of the new host
type: string
roleID:
description: ID of the role you want to assign
type:
- string
- 'null'
networkID:
description: ID of your network
type: string
examples:
- name: My new host
roleID: role-PZEDBXHQEXKAKJPZ6XOQTIAJA4
networkID: network-KAOWMXZHZWYVMGGFKM22XEGYLE
security:
- api_key:
- hosts:create
- hosts:enroll
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
type: object
required:
- host
properties:
data:
type: object
properties:
host:
$ref: '#/components/schemas/Host'
enrollmentCode:
type: object
properties:
code:
type: string
lifetimeSeconds:
type: integer
format: int64
metadata:
type: object
example:
data:
host:
id: host-24NVITKMNU3YYCEDNFWKAOBX7I
organizationID: org-F63A24JGCLJV3ZEUTLRBISGETA
networkID: network-KAOWMXZHZWYVMGGFKM22XEGYLE
roleID: role-PZEDBXHQEXKAKJPZ6XOQTIAJA4
name: lol wat
ipAddress: 100.100.0.29
staticAddresses: []
listenPort: 0
isLighthouse: false
isRelay: false
createdAt: '2023-01-25T18:15:27Z'
isBlocked: false
enrollmentCode:
code: H8NEbm99QvupjqW1PsdVR9DNSiFmoQtJXyGTQxerlSU
lifetimeSeconds: 86400
metadata: null
'400':
description: Validation errors
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
$ref: '#/components/schemas/Errors'
examples:
existingHostName:
summary: A host already exists with the name
value:
errors:
- code: ERR_DUPLICATE_VALUE
message: value already exists
path: name
cannotFindNetwork:
summary: Cannot find the supplied networkID
value:
errors:
- code: ERR_INVALID_REFERENCE
message: referenced value is invalid (perhaps it does not exist?)
path: networkID
duplicateIpAddress:
summary: A host with the ipAdress supplied already exists
value:
errors:
- code: ERR_DUPLICATE_VALUE
message: value already exists
path: ipAddress
cannotFindRole:
summary: Cannot find the supplied roleID
value:
errors:
- code: ERR_INVALID_REFERENCE
message: referenced value is invalid (perhaps it does not exist?)
path: roleID
missingRoleID:
summary: Missing the required parameter `roleID`
value:
errors:
- code: ERR_MISSING_VALUE
message: must be present
path: roleID
lighthouseXorRelay:
summary: A host may only be a lighthouse OR a relay not both
value:
errors:
- code: ERR_INVALID_VALUE
message: lighthouse hosts must not also be relay hosts
lighthouseNeedsStaticIP:
summary: A lighthouse requires at least one static IP address.
value:
errors:
- code: ERR_INVALID_VALUE
message: lighthouse hosts must have at least one static ip address
path: staticAddresses
lighthouseNeedsStaticPort:
summary: A lighthouse requires a static listen port, like `4242`
value:
errors:
- code: ERR_INVALID_VALUE
message: lighthouse hosts must specify a static listen port
path: listenPort
relayNeedsStaticPort:
summary: A relay requires a static listen port, like `4242`
value:
errors:
- code: ERR_INVALID_VALUE
message: relay hosts must specify a static listen port
path: listenPort
'401':
$ref: '#/components/responses/ErrorUnauthorized'
default:
$ref: '#/components/responses/UnexpectedError'
/v1/hosts/{hostID}:
delete:
summary: Delete a host
operationId: deleteHost
tags:
- hosts
parameters:
- name: hostID
in: path
required: true
schema:
type: string
example: host-24NVITKMNU3YYCEDNFWKAOBX7I
security:
- api_key:
- hosts:delete
responses:
'200':
description: Deleted host successfully
content:
application/json:
schema:
type: object
required:
- data
- metadata
properties:
data:
type: object
metadata:
type: object
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'404':
description: Host not found
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: ERR_NOT_FOUND
message: resource not found
default:
$ref: '#/components/responses/UnexpectedError'
components:
securitySchemes:
api_key:
description: |
Get an api key from <https://admin.defined.net/settings/api-keys> with the perms for what you want to do.
type: http
scheme: bearer
schemas:
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: A static name for the error type
message:
type: string
description: A short human readable description of the error
path:
type:
- string
- 'null'
description: Describes the variable missing or malformed
Errors:
type: array
items:
$ref: '#/components/schemas/Error'
Host:
type: object
required:
- id
- organizationID
- networkID
- roleID
- name
- ipAddress
- staticAddresses
- listenPort
- isLighthouse
- isRelay
- createdAt
- isBlocked
properties:
id:
type: string
organizationID:
type: string
networkID:
type: string
roleID:
type:
- string
- 'null'
name:
type: string
ipAddress:
type: string
staticAddresses:
type: array
listenPort:
type: integer
format: int64
description: Will be zero if a regular host
isLighthouse:
type: boolean
default: false
isRelay:
type: boolean
default: false
createdAt:
type: string
isBlocked:
type: boolean
default: false
responses:
UnexpectedError:
description: Server Error
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/Errors'
readOnly: true
ErrorUnauthorized:
description: Unauthorized Error
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/Errors'
readOnly: true
example:
errors:
- code: ERR_UNAUTHORIZED
message: unauthorized
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment