apiary.apib

FORMAT: 1A
HOST: https://api.gemnasium.com/v1

# Gemnasium

Gemnasium API lets you interract with your Gemnasium projects and more.

## API client

Gemnasium provides a client binary to easily communicate with the API. Read more on https://github.com/gemnasium/toolbelt#readme

## API versioning

Gemnasium API is versioned by appending the version number at the end of the root URL (ie: https://api.gemnasium.com/v1).

The current stable version of the API is `v1`.

## Rate limiting

There is currently no rate limit on the Gemnasium API. We may apply a rate limit in the future.

# Group Authentication

Each API request should be authenticated using HTTP Basic authentication with 'X' as the login, and the Gemnasium user API key as the password.

The user API key can be found at the bottom of the [user settings page](https://gemnasium.com/settings/) or can be requested over the API.

## POST /login

Authenticate a user and return her/his user API key

+ Request (application/json)

            { "email": "email@example.com", "password": "password" }

+ Response 200 (application/json)

            { "api_token": "authenticated_user_api_token" }

# Group Projects

A Gemnasium project has dependency files and it keeps track of the dependencies.

A project can either be synced with a remote repository (like a GitHub repo) or made of dependency files pushed via the API. It's said to be a "synced project" or a "pushed project".

Each project is identified by a unique slug. The slug can either be:

* a combinaison of host, account name and repo name when the project is "synced"
* a random string when the project is "pushed"

For instance, the slug of a project synced with http://github.com/gemnasium/toolbelt is github.com/gemnasium/toolbelt.

When not given, the host defaults to github.com. Omitting the host is now deprecated.

The project slug can be found on the project settings page.

## GET /projects

List the projects the authenticated user can access to

Projects are grouped by owner accounts. The projects owned by the authenticated appear as they belong to the "owned" account.

+ Response 200 (application/json)

        {
            "owned": [
                {
                    "slug": "randomly_generated_slug", "name": "project-1", "description" : "project-1 description", "origin": "gitlab", "private": true, "color": "green", "monitored": true, "unmonitored_reason": ""
                }, {
                    "slug": "gemnasium/project-2", "name": "project-2", "description" : "project-2 description", "origin" : "github", "private": false, "color": "yellow", "monitored": true, "unmonitored_reason": ""
                }
            ],
            "John Doe": [
                {
                    "slug": "randomly_generated_slug", "name": "project-1", "description" : "project-1 description", "origin": "gitlab", "private": true, "color": "green", "monitored": true, "unmonitored_reason": ""
                }, {
                    "slug": "gemnasium/project-2", "name": "project-2", "description" : "project-2 description", "origin" : "github", "private": false, "color": "yellow", "monitored": true, "unmonitored_reason": ""
                }
            ]
        }

## GET /projects/{slug}
Return the details of the a project.

+ Response 200 (application/json)

        {
            "slug": "gemnasium/API_project",
            "name": "API_project",
            "description": "This is a brief description of a project on Gemnasium",
            "origin": "github",
            "private": false,
            "color": "green",
            "monitored": true,
            "unmonitored_reason": ""
        }

## POST /projects

Create a project

This action applies to *pushed projects* only.

+ Parameters
    + name (string) ... Name
    + description (optional, string) ... A short description
    + origin (optional, string) ... Where the dependency files pushed via the API originate from. It can either be `offline` or `gitlab`. Default is `offline`.

+ Request (application/json)

        { "name": "API_project", "description": "", origin: "gitlab" }

+ Response 201 (application/json)

        { "name": "API_project", "slug": "randomly_generated_slug", "remaining_slot_count": 100 }

## PATCH /projects/{slug}

Update a project

It is possible to update the name, the description or the monitored attribute. All parameters are optional.

The name and description of a *synced project* can't be updated: they always match the name and description of the repo the project is synced with.

+ Parameters
    + name (optional, string) ... Name
    + description (optional, string) ... A short description
    + monitored (optional, boolean) ... Whether the project is watched by the user. A *synced project* is automatically synced with its repo when it's monitored.
    
+ Request (application/json)

        {
            "name": "New_project_name",
            "description": "New description",
            "monitored": false
        }

+ Response 200

        {
            "slug": "gemnasium/API_project",
            "name: "API_project",
            "description": "This is a brief description of a project on Gemnasium"
            "origin": "github",
            "private": false,
            "color": "green",
            "monitored": true,
            "unmonitored_reason": ""
        }

## POST /projects/{slug}/sync

Start project synchronization

The project synchronization proceeds in two steps:
* it updates the dependency files if the active branch has a new commit
* it updates the dependencies according to the dependency files

This action applies to *synced projects* only.

+ Response 204

# Group Dependency files

Dependency files content will **always** be base64 encoded

## GET /projects/{slug}/dependency_files

List the dependency files of a project

+ Response 200 (application/json)

        [
            { "id": "1", "path": "Gemfile", "content": "Gemfile base64 encoded content", "sha": "Gemfile SHA-1" },
            { "id": "2", "path": "Gemfile.lock", "content": "Gemfile.lock base64 encoded content", "sha": "Gemfile.lock SHA-1" }
        ]

## POST /projects/{slug}/dependency_files

Add dependency files to an existing project, or update existing ones.  
If a dependency file with the same path already exists, its content will be updated.

The request contains an array of dependency files where each file has a `path` and a `content`.  
The path of a dependency file is relative to its project directory. The parsing of a dependency file depends on its path (ie. the path `Gemfile` implies this is a Ruby Bundler dependency file, etc.).

**The files content must be base64 encoded.**

To use the auto-update feature, the revision and branch must be sent to Gemnasium prior to call auto-update.
The headers ```X-Gms-Revision``` and ```X-Gms-Branch``` must be set in the request.

This action applies to *pushed projects* only.

+ Request (application/json)
    + Headers
    
        Content-Type: application/json
        X-Gms-Revision: abcdef12356
        X-Gms-Branch: master
    
    + Body
    
        [
            { "path": "Gemfile", "content": "Gemfile base64 encoded content" },
            { "path": "Gemfile.lock", "content": "Gemfile.lock base64 encoded content" },
        ]

+ Response 200 (application/json)

        {
            "added": [{ "id": "1", "path": "Gemfile", "content": "Gemfile base64 encoded content", "sha": "Gemfile SHA-1" }],
            "updated": [{ "id": "2", "path": "Gemfile.lock", "content": "Gemfile.lock base64 encoded content", "sha": "Gemfile.lock SHA-1" }],
            "unchanged": [],
            "unsupported": ["picture.jpg"]
        }

## DELETE /projects/{slug}/dependency_files/{dependency_file-id}

Delete a dependency file

+ Response 204

# Group Dependencies

## GET /projects/{slug}/dependencies

List the dependencies of the requested project.

+ Response 200 (application/json)

        [
            {
                "package": {
                    "name": "gemnasium-gem",
                    "slug": "gems/gemnasium-gem",
                    "type": "rubygem",
                    "distributions": {
                        "stable": "3.1.0"
                    }
                },
                "requirement": ">=1.0.0",
                "locked": "2.0.0",
                "type": "development",
                "first_level": true,
                "color": "green"
            },
            {
                "package": {
                    "name": "rails",
                    "slug": "gems/rails",
                    "type": "rubygem",
                    "distributions": {
                        "prerelease": "4.2.5.rc2",
                        "stable": "4.2.5"
                    }
                },
                "requirement": "=3.1.12",
                "locked": "3.1.12",
                "type": "runtime",
                "first_level": true,
                "color": "red"
            }
        ] 

# Group Dependency alerts
## GET /projects/{slug}/alerts

List the dependency alerts the given project is affected by

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "advisory": {
                    "id": 1,
                    "title": "XSS vulnerability"
                },
                "dependency": {
                    "id": 1
                },
                "open_at": "2014-05-07T09:59:53.738404Z",
                "status": "acknowledged"
            },
            {
                "id": 2,
                "advisory": {
                    "id": 2,
                    "title": "DOS vulnerability"
                },
                "dependency": {
                    "id": 1
                },
                "open_at": "2014-05-07T09:59:53.738404Z",
                "status": "closed"
            }
        ]

# Group Live evaluation

**Those endpoints are reserved for Gold members only**

The Gemnasium API is able to parse a set of dependency files without creating any project.

The dependency file evaluation is asynchronous and proceeds in two steps:

* post the dependency files and get a job id back
* poll the job till it has a result

The result of the job is similar to the description of a project (ie. it has colors, dependencies and alerts).

**The files content must be base64 encoded.**

## POST /evaluate

Process a set of dependency files and return a job

+ Request (application/json)

        {
            "dependency_files": [
                {
                    "path": "Gemfile",
                    "content": "base64 Gemfile content"
                },
                {
                    "path": "Gemfile.lock",
                    "content": "base64 Gemfile.lock content"
                }
            ]
        }

+ Response 200 (application/json)

        { "job_id": "123" }

## GET /evaluate/{job-id}

Get the status of a job, and possibly its result

The job status can either be:

* `queued` if the job is enqueued but not started yet
* `working` if the job is under progress
* `completed` when the result of the job are available
* `failed` if the job has failed
* `killed` if the job has been manually killed

When completed, the job has a result that includes:

* an overall color for each environment type (runtime and development)
* a list of dependencies; each dependency has a color, a package and a list of advisories

+ Response 200 (application/json)

        {
            "status": "completed",
            "result": {
                "runtime_status": "red",
                "development_status": "yellow",
                "dependencies": [
                    {
                        "package": {
                            "name": "actionmailer",
                            "type": "Rubygem",
                            "slug": "gems/actionmailer"
                        },
                        "requirement": "= 4.0.4",
                        "locked": "4.0.4",
                        "type": "runtime",
                        "first_level": false,
                        "color": "red",
                        "advisories": [ { "id": 1 }, { "id": 2 }]
                    },
                    {
                        "package": {
                            "name": "actionpack",
                            "type": "Rubygem",
                            "slug": "gems/actionpack"
                        },
                        "requirement": "= 4.0.4",
                        "locked": "4.0.4",
                        "type": "runtime",
                        "first_level": false,
                        "color": "yellow",
                        "advisories": []
                    },
                    {
                        "package": {
                            "name": "active_link_to",
                            "type": "Rubygem",
                            "slug": "gems/action_link_to"
                        },
                        "requirement": ">= 0",
                        "locked": "1.0.2",
                        "type": "development",
                        "first_level": true,
                        "color": "green",
                        "advisories": []
                    }
                ]
            }

# Group Auto update

*This feature is currently in beta and only available for eligible projects.*

A Gemnasium project can be automatically tested against dependencies updates once the feature has been enabled.

## POST /projects/{slug}/branches/{branch_name}/update_sets/next

Return the next update_set available for the given project, on a given branch and for a specific commit. An update set is a combination of dependencies to be updated simulteanously.

+ Parameters
    + revision (required, string) ... Current revision identifier.


+ Request (application/json)

        { "revision": "e4a87ac551ce8e02e314eebd3cf00a436a4cb73f" }

+ Response 200 (application/json)

        {
            "id":1,
            "requirement_updates": {
                "Rubygem" : [
                    {
                        "file": {
                            "path":"Gemfile",
                            "sha":"dc6bdc865c85a4f5c6ef0f4ba8909d8652fd8cd0"
                        },
                        "patch": "--- Gemfile\n+++ Gemfile\n@@ -4 +4 @@\n-gem \"rails\", \"3.0.0.beta3\"\n+gem \"rails\", '~> 4.0.3'\n@@ -5 +5 @@\n-gem \"warden\", \"0.10.3\"\n+gem \"warden\", '~> 1.2.3'\n@@ -7 +7 @@\n-gem \"webrat\", \"0.7\"\n+gem \"webrat\", '~> 0.7.3'\n"
                    }
                ]
            },
            "version_updates": {
                "Rubygem" : [
                  {
                      "package": {
                          "type": "Rubygem",
                          "name": "twitter-bootstrap-rails"
                      },
                      "old_requirement": "~> 2.1",
                      "old_version": "2.2.8",
                      "target_version": "2.3.1"
                  },
                  {
                      "package": {
                          "type": "Rubygem",
                          "name": "sqlite3"
                      },
                      "old_requirement": "~> 1.3.2",
                      "old_version": "1.3.8",
                      "target_version": "1.3.9"
                  }
              ]
            }
        }

## PATCH /projects/{slug}/branches/{branch_name}/update_sets/{id}
Update an update set with test result.

+ Parameters
    + state (required, string) ... UpdateSet state. Accepted values are :  `invalid`, `test_passed`, `test_failed`.
    + dependency_files (optional, array) ... List of dependency files, after update has been applied.

+ Request (application/json)

        {
            "state": "test_passed",
            "dependency_files": [
                {
                    "path": "Gemfile.lock",
                    "content": "base64 content"
                }
            ]
        }

+ Response 200 (application/json)