Skip to content
This repository
tree: 5c1125dbf9
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 502 lines (431 sloc) 14.958 kb

Nodejitsu Web-hook API

Access the Admin section on your open source node.js Github repository. Click Service Hooks and then Nodejitsu. You will be presented with a form with four fields:

The Github Interface for Nodejitsu

Select Active and hit Update Settings. From now on every-time you commit to Github (in the designated deployment branch) we will deploy that application for you. That simple.

Monitoring deployments

There's several ways to access the deployment status in the Nodejitsu Webhook API, and you can find the complete documentation at webhooks.nodejitsu.com.

The most fun way to monitor your deployment is with the realtime status changes feed.

# if your username is foo and password is bar this would be 
# https://foo:bar@webhooks.nodejitsu.com/1/status/foo/changes
curl https://username:password@webhooks.nodejitsu.com/1/status/username/changes?include_docs=auto

This will create an HTTP keep alive connection that pushes the status to you in realtime every time someone invokes our API:

{
  "id": "https://webhooks.nodejitsu.com/1/status/dscape/changes/2b3de47c2ce04a9dda4d31aac5000bab",
  "app_name": "hello-world-api-flatiron",
  "uuid": "aa6e9b1332436698771",
  "status": "ok",
  "provider": "travis",
  "commit": "dscape/hello-world-flatiron-api/96410ed970f6224a4cd3c450150c5d65bbc77fcd"
}

Each request to our API is logged with a unique uuid, so you can use it to refer possible issues to our support staff.

We are now ready to deploy, go back to Github and click Test Hook. You should be up and running shortly.

Travis

What about continuous integration? We added Travis-CI so you can feel safe about your deployments. Simply add something like this in your .travis.yml file.

notifications:
  webhooks: 
    urls:
      - http://webhooks.nodejitsu.com/1/deploy
    on_success: always
    on_failure: never

Internally our API will try to see if you have Travis configured like this, and if you do it will put the deployment request from Github on a hold until Travis informs us all tests have passed.

If tests failed we won't deploy. Simple.

Deploying Private Repos & Commit Status API

If you authorize access so we can use your github account we can do more fun stuff like allowing you to deploy your private repositories, or even update your commit status and check if a deployment worked directly in github. We don't save any passwords - we just use the password to retrieve a token to save.

Commit Status API

To authorize simply do:

curl -X POST \
  -H "Content-type: application/json" \
  --data "{ \"credentials\": githubUser:githubPassword }" \
  https://nodejitsuUser:nodejitsuPass@webhooks.nodejitsu.com/1/auth/github 

But wait, I have API keys I can't commit to Github as open source?!

Don't worry, you can use jitsu set env to set environment variables that you can access with process.env. Check our handbook for more information. Environment variables set this way persist across deployments and are also available in our webops application.

API Documentation

Deploy

POST /
POST /1/deploy

Deploy a new application with a given payload.

Check Sample Payloads for examples. This method is normally called by a github or travis web-hook.

You must configure the github webhook to use the travis webhook. Works under the assumption that if your repository has a .travis.yml file and that contains at least one webhook notification we shouldn't deploy from the github request, but instead wait until travis triggers the notify event and calls our API. This effectively means that if travis tests don't pass your application does not get deployed.

curl -X POST -d @file https://user:pass@webhooks.nodejitsu.com/1/deploy

Authentication can use a pair of user:pass or user:apiToken.

Accept

Content-type Description
application/json A valid JSON payload

Response Headers

Header Type Description
x-api-uuid String - UUID A unique id for your request. We keep tracks of these to help you thru support
x-api-version String - Semantic Version The current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

Error Status Code Reason
deploy:db:failed_to_store_payload 503 Our database isn't responding or timed out
deploy:provider:not_supported 400 You tried to deploy an invalid payload
deploy:github:no_pkg_json 502 We couldn't get package.json from github. This may happen because you are trying to deploy a private repo
deploy:auth:bad_creds 401 You didn't provide valid Basic Auth in your HTTP request
deploy:github:download_tarball 502 Failed to get the tarball from github
deploy:nodejitsu:upload_tarball 502 Failed to upload the tarball to nodejitsu
deploy:tar:* 500 There was a system failure when extracting the tar
deploy:nodejitsu:start_app 500 Failed to start nodejitsu application
deploy:no_payload 400 You didn't provide a payload

Status

GET /1/status/:user/webhooks
GET /1/status/:user/webhooks/:application

Gets the install status for a specific user. Useful to determine if the deploy worked, or why it failed. :user is your nodejitsu username and :application is your application name.

curl https://dscape:password@webhooks.nodejitsu.com/1/status/dscape/webhooks/hello-world-api-flatiron?limit=10\&skip=20

Query String Parameters

Key Type Description
limit Integer Number of log entries to display per page
skip Integer Number of log entries to skip. e.g. if you saw 10 already, you might do a skip=10

Response Headers

Header Type Description
x-api-uuid String - UUID A unique id for your request. We keep tracks of these to help you thru support
x-api-version String - Semantic Version The current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

Error Status Code Reason
mw:auth:not_you 401 You are trying to get status that don't belong to you
mw:auth:auth_server_down 500 We couldn't verify your credentials
mw:auth:unauthorized 401 Your username/password combination doesn't match our records
mw:auth:no_username 401 Your user document is in a bad state, contact support
status:db:not_found 404 Didn't find that log entry
status:db:get_by_id 500 The database couldn't complete your query
status:db:query_fail 500 The database couldn't complete your query

Changes

GET /1/status/:user/changes/
GET /1/status/:user/changes/:id

Streams log files as you deploy application with a changes stream. When you provide an id it will just return that entry and close the http connection.

curl https://dscape:password@webhooks.nodejitsu.com/1/status/dscape/changes?include_docs=true

Query String Parameters

Key Type Description
include_docs Boolean Will add an extra property `doc` (containing the full log document) to each log entry that is displayed. Use "auto" for automatically expanding errors and summarizing ok statuses

Response Headers

Header Type Description
x-api-uuid String - UUID A unique id for your request. We keep tracks of these to help you thru support
x-api-version String - Semantic Version The current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

Error Status Code Reason
mw:auth:not_you 401 You are trying to get status that don't belong to you
mw:auth:auth_server_down 500 We couldn't verify your credentials
mw:auth:unauthorized 401 Your username/password combination doesn't match our records
mw:auth:no_username 401 Your user document is in a bad state, contact support
status:db:query_fail 500 The database couldn't complete your query
status:changes:timeout 408 The socket connection timeout. Please re-connect
status:changes:fatal 500 There was an error in the underlying connection

auth

GET /1/auth/github

Tries to get authorization from github, so elevated privileges can be used on that service. This will give us access to get working code from your repositories and change the status of a specific pull request

curl -X POST nodejitsuUser:nodejitsuPwd@webhooks.nodejitsu.com/1/auth/github --data '{"credentials":"githubUser:githubPass"}' --header "Content-type: application/json" 

Query String Parameters

The app parameter exists so you can restrict usage of a token to a individual application. This is useful can then commit status can only be applied to that specific application, and other third party tokens will not be returned.

However be careful, when specifying an application we will not be able to use these credentials to access the repository (because when we do that for the first time we still don't know the app name, we learn that from the package.json file).

Bottom line if you want to do deployments for private repositories do not specify app or you will fail.

Key Type Description
app String Will restrict the usage of this token to a application. If not provided a wildcard will be used.

Response Headers

Header Type Description
x-api-uuid String - UUID A unique id for your request. We keep tracks of these to help you thru support
x-api-version String - Semantic Version The current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

Error Status Code Reason
mw:auth:not_you 401 You are trying to get status that don't belong to you
mw:auth:auth_server_down 500 We couldn't verify your credentials
mw:auth:unauthorized 401 Your username/password combination doesn't match our records
mw:auth:no_username 401 Your user document is in a bad state, contact support
auth:github:get_user_failed 500 When retrieving the user from the nodejitsu api we got a non 200 response. The api might be down, or perhaps authorization credentials where changed
auth:github:update_user_failed 500 We tried to update the user but it failed. Just like above, reasons are varied so contact support if you see this
auth:github:no_credentials 400 Credentials were not provided. Check query string parameters for details
auth:github:bad_credentials 400 Credentials were provided but not in the username:password format. Check query string parameters for details
auth:github:github_pairing_failed 401 We tried to authenticate with github but it failed
Something went wrong with that request. Please try again.