Introduction

This documentation is for Conch API version 3.0. For previous versions, see here.

The Conch ecosystem is designed to make the deployment of new server hardware easier, specifically targetting equipment to be used in the Joyent SmartDatacenter product line.

Conch has two major backend systems.

First, edge software boots new hardware, upgrades firmware, performs burn-in testing, and gathers the general state of the hardware. (This software is currently closed source.)

Second, this edge data is fed into the Conch API (this codebase) where the data is processed, validated, stored, and reported upon.

The Ecosystem

• The Web UI
• The CLI Tooling

Development

Our development process is documented over here.

Routes / URLs

Unless otherwise specified, all routes require authentication: a user must POST /login first, and then use the provided JSON Web Token for subsequent requests.

Full access is granted to system admin users; otherwise, access restrictions are as noted.

The majority of our endpoints consume and respond with JSON documents that conform to a set of JSON schema. These schema can be found in the json-schema directory in the main repository, as well as on this documentation site.

Successful (HTTP 2xx code) response structures are as described for each endpoint; potential error (HTTP 4xx) responses are also listed, as well as the normal errors common across all endpoints, as noted below:

• failure to validate query parameters: HTTP 400, response.json#/$defs/QueryParamsValidationError
• failure to validate request body payload: HTTP 400, response.json#/$defs/RequestValidationError
• all other errors, unless specified, use the generic error structure, response.json#/$defs/Error
• failure to properly authenticate (user not found, password incorrect, missing authentication token): HTTP 401
• user is not authorized for this endpoint: HTTP 403

Available top-level routes are:

• Conch::Route
  • /ping
  • /version
  • /login
  • /logout
  • /refresh_token
  • /me
• Conch::Route::Build
  • /build
• Conch::Route::Datacenter
  • /dc
• Conch::Route::Device
  • /device
• Conch::Route::DeviceReport
  • /device_report
• Conch::Route::HardwareProduct
  • /hardware_product
• Conch::Route::HardwareVendor
  • /hardware_vendor
• Conch::Route::JSONSchema
  • /json_schema
• Conch::Route::RackLayout
  • /layout
• Conch::Route::Organization
  • /organization
• Conch::Route::Rack
  • /rack
• Conch::Route::RackRole
  • /rack_role
• Conch::Route::Relay
  • /relay
• Conch::Route::DatacenterRoom
  • /room
• Conch::Route::User
  • /user
• Conch::Route::ValidationPlan
  • /validation_plan
• Conch::Route::ValidationState
  • /validation_state

Features

The Conch API has many features to make it a fully-functional and robust REST application.

• Most endpoints (save trivial ones such as GET /ping) require the user to be authenticated. This lets us mount the application on a world-reachable host while still protecting our private data. After POST /login, the user is issued a Java Web Token for future access.

• Access to various components in the system are protected by a layered system of roles; for example, a user can be granted access to data pertaining to just one build, without having access to historical build data or other devices in the system; or, read-only access to some parts and write access to other parts.

• All transactions are logged in local files for later analysis. Errors are also sent up to Rollbar to ensure immediate developer attention.

• All endpoints have strict error checking in both request and response payloads, with errors spelled out clearly in the response to enable easy development of client code. The payload schemas can be found here.

• Addition, modification and deletion of users, organizations and builds trigger email notification to the relevant administrators.

• Data is stored in Postgres and backed up nightly to a Manta store.

• All parts of the application are unicode-clean. 우리는 한국어를 합니다!

Database schemas

The full database schema: .

Database tables relevant to user roles: .

Database tables relevant to device data: .

Database tables relevant to datacenters and device locations: .

Database tables relevant to device validations: .

Modules

Individual module documentation can be found here.

Script documentation can be found here.

JSON Schema defining request and response payloads can be found here.

Copyright / License

Copyright Joyent, Inc.

This Source Code Form is subject to the terms of the Mozilla Public License, v.2.0. If a copy of the MPL was not distributed with this file, you can obtain one at https://www.mozilla.org/en-US/MPL/2.0/.