FORMAT: 1A

HOST: https://api.codecorps.org

# API Reference

The Code Corps API is a [JSON API](http://jsonapi.org/)-based REST API built in Elixir. You can visit the [API project on GitHub](https://github.com/code-corps/code-corps-api).

This document outlines how to interact with the API's resource-oriented URLs. JSON API errors returned by the API are also documented along with their HTTP status codes.

This API is intended for direct consumption by the Code Corps Ember application.

The production API can be found at `https://api.codecorps.org`.

The staging API can be found at `http://api.pbqrpbecf.org`.

The remote development API can be found at `http://api.pbqrpbecf-qri.org`.

# Group Authentication

When using the API's authenticated endpoints you can authenticate users by exchanging the `username` (email address) and `password` for a JSON Web Token.

## JSON Web Token Exchange [/token]

Exchange email and password for `token`.

### Exchange email and password for token [POST]

+ Request

+ Attributes

+ username: `me@testuser.org` (string, required) - The user's email address.

+ password: `password` (string, required)

+ Headers

Content-Type: application/vnd.api+json

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Valid Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token No User With Email Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Password Response)

## JSON Web Token Refresh [/token/refresh]

### Refresh the token [POST]

+ Request

+ Attributes

+ token: `eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJVc2VyOjEiLCJleHAiOjE0NzY3NTQ2MTcsImlhdCI6MTQ3NDE2MjYxNywiaXNzIjoiQ29kZUNvcnBzIiwianRpIjoiMDY2ODQ0OWYtNWY5OC00ODVkLWI4NTktNjRhZDhmZDU3NWQ4IiwicGVtIjp7fSwic3ViIjoiVXNlcjoxIiwidHlwIjoidG9rZW4ifQ.Y80alu1UEmk4uxGgA7ORVdS8ikuUJFxCozyK6S9UeaLW392Vhti4d1Y1IXivWA_j9TKjADhqTQnMihbCzUiLsA` (string, required) - The JSON Web Token provided in the create step.

+ Headers

Content-Type: application/vnd.api+json

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Valid Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Expired Response)

# Group Categories

This endpoint is for creating and returning the categories available for projects and users.

The Category resource allows us to categorize projects (Project Category), as well as identify a user's interests (User Category). The categories of "Society", "Technology" or "Government", for example, could all be used to categorize projects or match to a user's given interests.

## Categories [/categories]

### Create a category [POST]

+ Request

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Category Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

### List all categories [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Categories Response)

## Category [/categories/{id}]

### Retrieve a category [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Category Response)

+ Response 404 (application/vnd.api+json; charset=utf-8)

+ Attributes (Record Not Found Response)

### Update a category [PATCH]

+ Request

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Category Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

+ Response 404 (application/vnd.api+json; charset=utf-8)

+ Attributes (Record Not Found Response)

# Group Comments

This endpoint is for creating and returning comments.

## Comments [/comments]

You can list all comments or retrieve individual comments, as well as create and update comments.

### Create a comment [POST]

+ Request

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Attributes (Comment Create Request)

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Comment Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

### Filter comments by list of ids [GET /comments{?filter[id]}]

+ Request

+ Attributes

+ `filter[id]`: `1,2,3` (string, required) - Comma separated string of `ids` to filter by.

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Comments Response)

## Comment [/comments/{id}]

+ Parameters

+ id (number, required)

### Update a comment [PATCH]

+ Request

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Attributes (Comment Update Request)

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Comment Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

# Group Donation Goals

This resource describes one of any number of donation goals a project might have. A project cannot create a donation goal until they have started accepting payment with Stripe.

## Donation Goals [/donation-goals]

### Create a donation goal [POST]

To create a donation goal the user must be a site admin or the owner of the referenced project.

+ Request

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Attributes (Donation Goal Create Request)

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Donation Goal Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

+ Response 404 (application/vnd.api+json; charset=utf-8)

+ Attributes (Record Not Found Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

### List all donation goals [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Donation Goals Response)

### Filter by id [GET /donation-goals{?filter[id]}]

+ Request

+ Attributes

+ `filter[id]`: `1,2,3` (string, required) - Comma separated string of `ids` to filter by.

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Donation Goals Response)

+ Response 404 (application/vnd.api+json; charset=utf-8)

+ Attributes (Record Not Found Response)

## Donation Goal [/donation-goals/{id}]

+ Parameters

+ id (number, required)

### Retrieve a donation goal [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Donation Goal Response)

+ Response 404 (application/vnd.api+json; charset=utf-8)

+ Attributes (Record Not Found Response)

### Update a donation goal [PATCH]

To update a donation goal the user must be a site admin or the owner of the referenced project.

+ Request

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Attributes (Donation Goal Update Request)

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Donation Goal Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

+ Response 404 (application/vnd.api+json; charset=utf-8)

+ Attributes (Record Not Found Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

### Delete a donation goal [DELETE]

To delete a donation goal the user must be a site admin or the owner of the referenced project.

+ Request

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 204 (application/vnd.api+json; charset=utf-8)

+ Attributes (No Content Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

+ Response 404 (application/vnd.api+json; charset=utf-8)

+ Attributes (Record Not Found Response)

# Group Github App Installations

This endpoint is used for creating, updating, and retrieving information about a GitHub App installation. See the GitHub API documentation for more details about [the installation process of GitHub Apps](https://developer.github.com/apps/building-integrations/setting-up-a-new-integration/about-choosing-an-integration-type/#installation-processes-for-integrations).

To simplify, Code Corps has a GitHub App which is installed to a GitHub user's or GitHub organization's account _on GitHub_. This grants Code Corps read and write access to the GitHub API on behalf of that user or organization.

You'll notice project and user relationships, which are only useful when setting up an installation for the first time. When GitHub redirects the user back to Code Corps after installing the GitHub App, our client only has access to the installation's `installation_id` in a query parameter. Because of this, before we direct the user to GitHub to install our App, we need to create a GithubAppInstallation record that keeps track of the user who requested it, the project it was requested on. This installation will be automatically marked with the `state` set to `"unprocessed"` and the `origin` set to `"codecorps"`.

Note that this does not mean there's actually an installation yet! The user hasn't been to GitHub. We're just keeping track of that installation for later.

Once the user installs the App on GitHub, GitHub will send an `installation` webhook to our API. The payload includes a `sender` key containing the GitHub account (along with its `id`) that performed the installation. The user is then automatically redirected back to Code Corps.

Once the user is back on Code Corps, we want to redirect the user back to the target project. Luckily, the `installation_id` GitHub provided in the query parameter yields enough information to match it to our authenticated user's GithubAppInstallation record created in the previous step.

We match:

- the `installation_id` in the query parameter

- the `installation` webhook's `installation_id` and `sender`'s account `id`

- our user's GitHub account `id`

These pieces of information are enough to tell us who installed the application. And because we stored the target project for this first installation, we can redirect our user. The API may need to do some processing work to complete the setup, but once the `state` has moved to `processed`, the client can redirect to the project's integrations page using the project relationship.

Keep in mind that an installation could be used across multiple projects. And because an installation can be installed at the _organization_ level on GitHub, that means the user who requested the installation is likely not be the only user with permissions on GitHub to modify or even uninstall the GitHub App. The user relationship specified here is _only_ useful for the first installation of a user on a project, due solely to the complicated redirection flow detailed above.

## Github App Installations [/github-app-installations]

### Create a Github app installation [POST]

+ Request

+ Attributes (Github App Installation Create Request)

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Github App Installation Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

### Filter by id [GET /github-app-installations{?filter[id]}]

+ Request

+ Attributes

+ `filter[id]`: `1,2,3` (string, required) - Comma separated string of `ids` to filter by.

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Github App Installations Response)

## Github App Installation [/github-app-installations/{id}]

+ Parameters

+ id (number, required)

### Retrieve a Github app installation [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Github App Installation Response)

# Group Github Repos

This endpoint is used for retrieving information about a Github Repo for display only.

Note that a Github Repo relates 1:1 to a Github App Installation, since only a single installation of the Code Corps GitHub App will happen on a GitHub account. A Github Repo will never be duplicated and does not need to have a many-to-many relationship.

## Github Repos [/github-repos]

### Filter by id [GET /github-repos{?filter[id]}]

+ Request

+ Attributes

+ `filter[id]`: `1,2,3` (string, required) - Comma separated string of `ids` to filter by.

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Github Repos Response)

## Github Repo [/github-repos/{id}]

+ Parameters

+ id (number, required)

### Retrieve a Github repo [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Github Repo Response)

# Group Organization Github App Installations

## Organization Github App Installations [/organization-github-app-installations]

### Create an Organization Github app installation [POST]

+ Request

+ Attributes (Organization Github App Installation Create Request)

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Github App Installation Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

### Filter by id [GET /organization-github-app-installations{?filter[id]}]

+ Request

+ Attributes

+ `filter[id]`: `1,2,3` (string, required) - Comma separated string of `ids` to filter by.

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Github App Installations Response)

### List all organization github app installations [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Github App Installations Response)

## Organization Github App Installation [/organization-github-app-installations/{id}]

+ Parameters

+ id (number, required)

### Retrieve an Organization github app installation [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Github App Installation Response)

### Delete an Organization Github App Installation [DELETE]

+ Request

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 204 (application/vnd.api+json; charset=utf-8)

+ Attributes (No Content Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

#Group Organization Invites

This endpoint is for Creating, Updating, returning Organization Invites on Code Corps.

##Organization Invites [/organization-invites]

### Create an organization invite [POST]

Admin creates new organization invites which contains `email` and `title`. A `code` is automatically generated on creation.

On successful creation an email is sent to the given `email` address.

+ Request

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer <token>

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Invite Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

### Filter by id [GET /organization-invites{?filter[id]}]

+ Request

+ Attributes

+ `filter[id]`: `1,2,3` (string, required) - Comma separated string of `ids` to filter by.

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Invites Response)

+ Response 400 (application/vnd.api+json; charset=utf-8)

+ Attributes (Filter Missing Response)

## Organization Invite [/organization-invites/{id}]

+ Parameters

+ id (number, required)

### Retrieve an organization invite [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Invite Response)

+ Response 404 (application/vnd.api+json; charset=utf-8)

+ Attributes (Record Not Found Response)

### Update an organization invite [PATCH]

+ Request (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Invite Resource)

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Invite Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

# Group Organizations

This endpoint retrieves Organizations on Code Corps. Organizations usually have one or more Projects.

A valid `invite_code` parameter is required to create an Organization. Without this parameter, only admin users are allowed to create new organizations.

## Organizations [/organizations]

### Create an organization [POST]

+ Request

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer <token>

+ Attributes (Organization Create Request)

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

### Filter by id [GET /organizations{?filter[id]}]

+ Request

+ Attributes

+ `filter[id]`: `1,2,3` (string, required) - Comma separated string of `ids` to filter by.

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organizations Response)

+ Response 400 (application/vnd.api+json; charset=utf-8)

+ Attributes (Filter Missing Response)

## Organization [/organizations/{id}]

+ Parameters

+ id (number, required)

### Retrieve an organization [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Response)

+ Response 404 (application/vnd.api+json; charset=utf-8)

+ Attributes (Record Not Found Response)

### Update an organization [PATCH]

+ Request (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Resource)

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Organization Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

# Group Password

This endpoint is a parent route for reset and forgot password endpoints

## Forgot [/forgot]

### Forgot Password [POST]

+ Request

+ Attributes (Forgot Password Request)

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer <token>

+ Response 200 (application/vnd.api+json; charset=utf-8)

## Reset [/password/reset]

Reset Password resource allow a user to reset their password

### Reset Password [POST]

+ Request

+ Attributes (Reset Password Request)

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Valid Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token No User With Email Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Password Response)

# Group Previews

Preview resources allow a user to create a temporary HTML preview for any kind of markdown.

## Preview [/previews]

### Create a preview [POST]

+ Request

+ Attributes (Preview Create Request)

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Preview Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

# Group Project Categories

This resource identifies a relationship between a Project and a Category. For example, the category of "Society" may belong to a given project.

## Project Categories [/project-categories]

### Create a project category [POST]

+ Request

+ Attributes (Project Category Create Request)

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Project Category Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

### List all project categories [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Project Categories Response)

## Project Category [/project-categories/{id}]

+ Parameters

+ id (number, required)

### Retrieve a project category [GET]

+ Request

+ Headers

Accept: application/vnd.api+json

+ Response 200 (application/vnd.api+json; charset=utf-8)

+ Attributes (Project Category Response)

+ Response 404 (application/vnd.api+json; charset=utf-8)

+ Attributes (Record Not Found Response)

### Delete a project category [DELETE]

+ Request

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 204 (application/vnd.api+json; charset=utf-8)

+ Attributes (No Content Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 403 (application/vnd.api+json; charset=utf-8)

+ Attributes (Forbidden Response)

# Group Project Github Repos

This resource identifies a relationship between a Project and a GitHub repository. This relationship indicates whether the project is connected to a particular repository on GitHub and listening for events on that repository (like an issue being created). This is essential for the operation of the GitHub integration for syncing new issues and comments from GitHub to Code Corps.

For example, the project "Code Corps" may have the GitHub repositories of "code-corps-api" and "code-corps-ember" syncing with the project's tasks _on Code Corps itself_.

The organization owner can update their projects by connecting or disconnecting GitHub repositories that are available under their GitHub App installation. This will create or delete the Project Github Repo records, respectively.

## Project Github Repos [/project-github-repos]

### Create a project GitHub repo [POST]

+ Request

+ Attributes (Project Github Repo Create Request)

+ Headers

Accept: application/vnd.api+json

Authorization: Bearer {token}

+ Response 201 (application/vnd.api+json; charset=utf-8)

+ Attributes (Project Github Repo Response)

+ Response 401 (application/vnd.api+json; charset=utf-8)

+ Attributes (JSON Web Token Invalid Response)

+ Response 422 (application/vnd.api+json; charset=utf-8)

+ Attributes (Unprocessable Entity Response)

### List all project GitHub repos [GET]