NAV
curl

Introduction

Welcome to the Shipped API!

These are the endpoints you can use to develop your own tooling for using shipped.

Authentication

There are two ways to authenticate with Shipped.

Api Tokens

Each user has a secret api_token attribute. Find this token on the settings page. Passing this value as a querying parameter will authenticate that user.

Example Request

curl http://shipped-api.shipped-cisco.com/projects

Example Response

{
  "auth_token": "",
  "id":123456,
  "login":"adama",
  "avatar_url":"https://avatars.githubusercontent.com/u/123456?v=3",
   "html_url":"https://github.com/ikinsey",
  "name":"Bill Adama",
  "email":"wadama@galactica.net",
  "api_token": "XVlBwuiEEIkakjwoifslkw"
}

This endpoint authenticates the user associated with the token, and retuns that user.

HTTP Request

GET http://shipped-api.shipped-cisco.com/users/current?api_token=<TOKEN>

URL Parameters

Parameter Description
api_token The api token found in settings.

Once you’ve logged in with oauth on http://ciscocloud.github.io/shipped/dist/, you receive an encrypted, signed cookie that can be used for API authentication.

Dependencies

Dependencies are standard packages that your application can rely on.

Get all dependencies

Example Request

curl http://shipped-api.shipped-cisco.com/apps

Example Response

[
   {
      "id":"8db3b398-dd18-11e4-aa38-0090f5d8986c",
      "name":"Kafka",
      "deploy_image":"kafka",
      "image_source":"/cli/static/images/kafka.png",
      "category":"queues",
      "tags":[
         "apic"
      ],
      "description":"Containerized kafka service",
      "container_port":0,
      "container_cpu":0,
      "container_ram":0,
      "container_count":0
   },
   {...},
   {...}
]

Returns a list a list of available dependencies.

HTTP Request

GET http://shipped-api.shipped-cisco.com/apps

Buildpacks

Buildpacks are either language based or framework based and they can be used as a base container to start developing your service.

Get all buildpacks

Example Request

curl http://shipped-api.shipped-cisco.com/buildpacks?api_token=<TOKEN>

Example Response

[
   {
      "id":"8dc13969-dd18-11e4-aa3b-0090f5d8986c",
      "name":"PHP",
      "image_source":"http://shipped-api.shipped-cisco.com/cli/static/images/php.svg",
      "default_build_command":"mkdir -p output; cp *.png *.php output/",
      "default_test_command":"echo noop",
      "default_cpu":1,
      "default_ram":1001,
      "build_image":"bradrydzewski/php:5.5",
      "default_deploy_image":"tutum/apache-php:latest"
   },
   {...},
   {...}
]

Retrieves a list of all available buildpacks.

HTTP Request

GET http://shipped-api.shipped-cisco.com/buildpacks

Get a buildpack

Example Request

curl http://shipped-api.shipped-cisco.com/buildpacks/8dc13969-dd18-11e4-aa3b-0090f5d8986c

Example Response

{
   "id":"8dc13969-dd18-11e4-aa3b-0090f5d8986c",
   "name":"PHP",
   "image_source":"http://shipped-api.shipped-cisco.com/cli/static/images/php.svg",
   "default_build_command":"mkdir -p output; cp *.png *.php output/",
   "default_test_command":"echo noop",
   "default_cpu":1,
   "default_ram":1001,
   "build_image":"bradrydzewski/php:5.5",
   "default_deploy_image":"tutum/apache-php:latest"
}

Retrieves a buildpack.

HTTP Request

GET http://shipped-api.shipped-cisco.com/buildpacks/<BUILDPACK_ID>

URL Parameters

Parameter Description
BUILDPACK_ID The ID of the buildpack to retrieve

Projects

A project is a single entity that holds together any number of services and dependencies.

Get all projects

Example Request

curl http://shipped-api.shipped-cisco.com/projects

Example Response

[
   {
      "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
      "name":"php-hello-world",
      "users":null
   },
   {...},
   {...}
]

Retrieves a list of all publicly visible projects.

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects

Get your projects

Example Request

curl http://shipped-api.shipped-cisco.com/projects

Example Response

[
   {
      "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
      "name":"php-hello-world",
      "users":null
   },
   {...},
   {...}
]

Gets all projects for the currently authenticated user. This is determined by the cookie set on login.

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects

Get a project

Example Request

curl http://shipped-api.shipped-cisco.com/projects/b475996d-dd1e-11e4-9917-0090f5d8986c

Example Response

{
   "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
   "name":"php-hello-world",
   "users":null
}

Retrieves a project.

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the project to retrieve

Create a project

Example Response

{
   "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
   "name":"php-hello-world",
   "users":null
}

Creates a project and returns the created project.

HTTP Request

POST http://shipped-api.shipped-cisco.com/projects

Query Parameters

Parameter Default Description
name - The name of the project
description - A description of the project (optional)

Update a project

Example Response

{
   "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
   "name":"php-hello-world",
   "users":null
}

Updates a project, and returns the updated project.

HTTP Request

PUT http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the project to retrieve

Query Parameters

Parameter Default Description
name - The name of the project
description - A description of the project (optional)

Delete a project

Example Request

curl http://shipped-api.shipped-cisco.com/projects/b475996d-dd1e-11e4-9917-0090f5d8986c -X DELETE

This end point does not produce a response.

Deletes a project.

HTTP Request

DELETE http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the project to retrieve

Project Dependencies

Project dependencies are technologies that a project requires (not to be confused with services).

Get project dependencies

Example Request

curl http://shipped-api.shipped-cisco.com/projects/2b8dbde6-dd84-11e4-ab36-0090f5d8986c/dependencies

Retrieves all dependencies for a project.

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/dependencies

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to get dependencies

Create a project dependency

Creates a project dependency and returns that dependency.

HTTP Request

POST http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/dependencies

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to create a dependency

Query Parameters

Parameter Default Description
dependency_id - The id of the dependency to be added to this project. Find this from the /dependencies response

Project Environments

A project environment is a container to which releases can be deployed, e.g., development, staging, production.

Get project environments

Example Request

curl http://shipped-api.shipped-cisco.com/projects/2b8dbde6-dd84-11e4-ab36-0090f5d8986c/envs

Example Response

[
   {
      "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
      "project_id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
      "name":"Staging",
      "description":"Staging env for QA"
   },
   {...},
   {...}
]

Retrieves all environments for a project.

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/envs

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to get dependencies

Create a project environment

Example Response

{
   "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
   "project_id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
   "name":"Staging",
   "description":"Staging env for QA"
}

Creates a project environment and returns that environment.

HTTP Request

POST http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/envs

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to create a dependency

Query Parameters

Parameter Default Description
dependency_id - The id of the dependency to be added to this project. Find this from the /dependencies response

Releases

A release is a build deployed to a specific environment for a service.

Get all releases

Gets all the releases for an environment

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/envs/<ENV_ID>/releases

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to get releases
ENV_ID The id of the environment for which to get releases

Create a new release

Deploys a commit ref for a service to an environment on a project.

HTTP Request

POST http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/envs/<ENV_ID>/services/<SERVICE_ID>/releases

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to deploy a release
ENV_ID The environment for which to deploy the release
SERVICE_ID The service for which to deploy the release

Query Parameters

Parameter Default Description
commit_id - This is the git ref to be deployed. This ref must exist on the service that is being deployed.

Update a release

A release is a point in time snapshot so update is not valid operation.

Get the status of a releases

Gets the current status of releases for a service. This will return a list objects with information on the Marathon instances.

HTTP Request

GET /projects/<PROJECT_ID>/releases/<RELEASE_ID>/status

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to deploy a release
RELEASE_ID The id of the release for which to get the status

Builds

An individual build is a git commit to a specific service.

Get all project builds

Example Request

curl http://shipped-api.shipped-cisco.com/projects/2b8dbde6-dd84-11e4-ab36-0090f5d8986c/builds

Retrieves all builds for all services on a project.

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/builds

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to get builds

Get all service builds

Retrieves all builds for a service.

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/services/<SERVICE_ID>/builds

URL Parameters

Parameter Description
PROJECT_ID The id of the service’s project
SERVICE_ID The id of the service for which to update a build

Get a build log

Retrieves the log for a build.

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/services/<SERVICE_ID>/builds/<BUILD_ID>/log

URL Parameters

Parameter Description
PROJECT_ID The id of the service’s project
SERVICE_ID The id of the build’s service
BUILD_ID The id of the build for which to get the log

Configs

Get environment configs

Retrieves the configs for the project environment

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/envs/<ENV_ID>/config

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
ENV_ID The environment for which to get the configs

Get environment config

Retrieves a config for a project environment

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/envs/<ENV_ID>/config/<CONFIG_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
ENV_ID The environment for the config
CONFIG_ID The id of the config to get

Create an environment config

Creates a config for an environment

HTTP Request

POST http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/envs/<ENV_ID>/config

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
ENV_ID The environment for the config

Query Parameters

Parameter Default Description
deploy_image - Docker image to start the container
container_port Service port Port for the service to run on
container_cpu Service container cpu CPU allocation for the container
container_ram Service container ram RAM allocation for the container
container_count 1 Number of containers to run this service on
env_variables - Hash of keys/values that will be used as environment variables

Update a project environment config

Updates a config for a project environment, and returns the updated config

HTTP Request

PUT http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/envs/<ENV_ID>/config

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
ENV_ID The environment of the config

Query Parameters

Parameter Default Description
deploy_image - Docker image to start the container
container_port - Port for the service to run on
container_cpu - CPU allocation for the container
container_ram - RAM allocation for the container
container_count - Number of containers to run this service on
env_variables - Hash of keys/values that will be used as environment variables

Delete a project environment config

Deletes a config for a project environment

This endpoint does not return a value

HTTP Request

DELETE http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/envs/<ENV_ID>/config/<CONFIG_ID>

URL Parameters

Parameter Description
PROJECT_ID The config’s project
ENV_ID The config’s environment
CONFIG_ID The Id of the config to delete

Invite Tokens

Invite tokens allow the redeemer to join a Shipped project.

Create an invite token

Creates invite tokens for every email address. This endpoint also sends emails to the invitees.

HTTP Request

POST http://shipped-api.shipped-cisco.com/invite_tokens

Query Parameters

Parameter Default Description
project_id - The project to invite
emails - Array of email address to invite

Accept an invite

Accepts an invite by resolving an invite token. If authenticated, will add the current user to the project; otherwise, will instruct the client to redirect to the authentication view.

HTTP Request

GET http://shipped-api.shipped-cisco.com/invite_tokens/<INVITE_TOKEN>

URL Parameters

Parameter Description
INVITE_TOKEN The invite token to accept

Services

Services are github repositories that are part of a project.

Get all services for a project

Retrieves the services for a project

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/services

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to list services

Create a project service

Creates a service for a project, and returns the created service.

HTTP Request

POST http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/services

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to create the service

Query Parameters

Parameter Default Description
name - The name for the service
buildpack_id - The id of the buildpack to use for the service
image_source Buildpack default image The Docker image to use for the service
repository - The github repository for the service (will be created if it doesn’t already exist)
build_command Buildpack default_build_command The shell command to build the service
test_command Buildpack default_test_command The shell command to run tests for the service

Get a project service

Retrieves a project service

HTTP Request

GET http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/services/<SERVICE_ID>

URL Parameters

Parameter Description
PROJECT_ID The project id for the service
SERVICE_ID The service id to retrieve

Update a project service

Updates a service for a project, and returns the updated service.

HTTP Request

PUT http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/services

URL Parameters

Parameter Description
PROJECT_ID The project id for the service to be updated

Query Parameters

Parameter Default Description
name - The name for the service
buildpack_id - The id of the buildpack to use for the service
image_source Buildpack default image The Docker image to use for the service
repository - The github repository for the service (will be created if it doesn’t already exist)
build_command Buildpack default_build_command The shell command to build the service
test_command Buildpack default_test_command The shell command to run tests for the service

Delete a project service

Deletes a project service

HTTP Request

DELETE http://shipped-api.shipped-cisco.com/projects/<PROJECT_ID>/services/<SERVICE_ID>

URL Parameters

Parameter Description
PROJECT_ID The project id for the service
SERVICE_ID The service id to delete

Users

Get users in a project

Retrieves all users in a project

HTTP Request

GET http://shipped-api.shipped-cisco.com/users/for_project/<PROJECT_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to get users

Remove user from a project

Removes a user from a project.

HTTP Request

DELETE http://shipped-api.shipped-cisco.com/users/from_project/<PROJECT_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the project from which to delete the user

Get current user

Retrieves the currently authenticated user.

HTTP Request

GET http://shipped-api.shipped-cisco.com/users/current

Errors

The Kittn API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The kitten requested is hidden for administrators only
404 Not Found – The specified kitten could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The kitten requested has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many kittens! Slown down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.