GopherPit API Reference
1. Overview
This documentation describes the resources that make up the GopherPit API v1.
Go API client is implemented in package:
go get gopherpit.com/gopherpit/api
and documented using Godoc https://godoc.org/gopherpit.com/gopherpit/api.
2. Root endpoint
GopherPit can be used as a web service available on gopherpit.com address, or can be installed on-premises under an arbitrary domain. In either case all API paths are the same, but the endpoint is different.
To use publicly available service, the endpoint is:
https://gopherpit.com/api/v1
If on-premises installation is used, for example on domain go.example.com, the endpoint is:
https://go.example.com/api/v1
In the rest of this document gopherpit.com domain will be used in examples.
3. API Version
All API paths are prefixed with a version number, as part of the root endpoint.
This document describes only v1 version of the API.
4. Authentication
Each HTTP request requires X-Key header to be provided with a Personal Access Token as a value.
Token is unique for every GopherPit user account and can be generated on a website under Settings -> API access page. It is also filtered by IP subnets that user can specify on the same page.
If the token is missing or invalid, API will return a Unauthorized response.
Example:
curl -H "X-Key: 0036CHARACTERLONGPERSONALACCESSTOKEN" https://gopherpit.com/api/v1/domains
5. Rate Limiting
Rate limiting is configurable for Add and Update Domain requests. Additional HTTP response headers are returned with more information:
X-Ratelimit-Limit: The maximum number of requests that the user is permitted to make per hour.X-Ratelimit-Remaining: The number of requests remaining in the current rate limit window.X-Ratelimit-Reset: Seconds remaining until current rate limit window reset.X-Ratelimit-Retry: Seconds remaining until new requests are permitted when limit is reached.
If X-Ratelimit-Limit header is absent, no limit is enforced.
When rate limit is reached, a Too Many Requests response will be returned.
6. Resources
Request and response HTTP bodies are JSON-encoded as JSON objects. In this section, resources that represent data that GopherPit is managing are described as properties of JSON objects with their types and default values where properties may be omitted in the response.
6.1. Domain
Properties:
- id: (string)
- fqdn: (string)
- owner_user_id: (string)
- certificate_ignore: (boolean, default: false)
- disabled: (boolean, default: false)
Example:
{
"id": "wynw4p7wkj11r5qqnzhvr6yy1syy2vxed3cfvx3f",
"fqdn": "project.example.com",
"owner_user_id": "xpvzcny34b5jv69eyfd72bz4f4",
"disabled": true
}
6.2. Domain Tokens
Properties:
tokens: (array of objects)
- fqdn: (string)
- token: (string)
Example:
{
"tokens": [
{
"fqdn": "_gopherpit.example.com",
"token": "qroydpvr_28uIU7up_gikuIf0Yo="
},
{
"fqdn": "_gopherpit.project.example.com",
"token":"PW7XX5dIu38SPovHpYRIYpXd9jo="
}
]
}
6.3. Domain Users
Properties:
- owner_user_id: (string)
- user_ids: (array of strings)
Example:
{
"owner_user_id": "xpvzcny34b5jv69eyfd72bz4f4",
"user_ids": [
"34ddsdyca45634b5jv6ds727as",
"jkndsi333e9dsn7012n423jb31"
]
}
6.4. Package
Properties:
- id: (string)
- domain_id: (string)
- fqdn: (string)
- path: (string)
- vcs: (string, possible values: “git”, “hg”, “bzr”, “svn”)
- repo_root: (string)
- ref_type: (string, default: “”, possible values: “branch”, “tag”)
- ref_name: (string, default: “”)
- go_source: (string, default: “”)
- redirect_url: (string, default: “”)
- disabled: (boolean, default: false)
Example:
{
"id": "dqn54p1jwvfxhbebd35w59g2h605t9wm5e2eh206",
"domain_id": "ahy4mp0rvbsvpw469fk5debwvegrmqv761g5mafm",
"fqdn": "project.example.com",
"path": "/application",
"vcs": "git",
"repo_root": "https://git.example.com/me/my-app"
}
7. Queries
GopherPit API uses HTTP for communication and this section describes HTTP requests, their parameters and responses from the API. Beside specified error responses for each query, the Internal Server Error may occur.
If resource URL path is not valid, a Not Found response will be returned.
In case that the request body can not be decoded from JSON, a Bad Request response will be returned. All POST requests must have Content-Type: application/json header.
URL paths may contain parameters which are indicated with a variable name surrounded with curly brackets {}.
7.1. List Domains
GET /api/v1/domains
Query parameters:
- start: (string, default: “”) value returned in previous or next response property
- limit: (integer, default: 100) maximal elements in response
Response returns resource:
- domains: (array of Domain)
- count: (integer)
- previous: (string, default: “”)
- next: (string, default: “”)
Values from the previous and next fields can be passed as start query parameter to get a previous or next page in the listing.
curl -H "X-Key: TOKEN" \
https://gopherpit.com/api/v1/domains
{
"domains": [
{
"id": "wynw4p7wkj11r5qqnzhvr6yy1syy2vxed3cfvx3f",
"fqdn": "project.example.com",
"owner_user_id": "xpvzcny34b5jv69eyfd72bz4f4",
"disabled": true
}
],
"count": 1
}
Errors:
curl -H "X-Key: TOKEN" \
"https://gopherpit.com/api/v1/domains?start=missing.example.com"
{
"message": "Domain Not Found",
"code": 1000
}
7.2. Get Domain
GET /api/v1/domains/{ref}
URL parameters:
- ref: domain reference, can be domain ID or FQDN
Returns Domain resource.
curl -H "X-Key: TOKEN" \
https://gopherpit.com/api/v1/domains/project.example.com
{
"id": "wynw4p7wkj11r5qqnzhvr6yy1syy2vxed3cfvx3f",
"fqdn": "project.example.com",
"owner_user_id": "xpvzcny34b5jv69eyfd72bz4f4",
"disabled": true
}
Errors:
curl -H "X-Key: TOKEN"
https://gopherpit.com/api/v1/domains/missing.example.com
{
"message": "Domain Not Found",
"code": 1000
}
7.3. Add Domain
POST /api/v1/domains
Request body properties:
- fqdn: (string, required)
- owner_user_id: (string)
- certificate_ignore: (boolean)
- disabled: (boolean)
Response returns Domain resource.
curl -H "X-Key: TOKEN" \
-H "Content-Type: application/json" \
-d '{"fqdn":"example.localhost"}' \
https://gopherpit.com/api/v1/domains
{
"id": "rv3npp3e9yr8kghrjaxzzc9shd2yav2pa92n6k95",
"fqdn": "project.example.com",
"owner_user_id": "xpvzcny34b5jv69eyfd72bz4f4",
"disabled": false
}
Errors:
- Bad Request
- Domain Already Exists
- Domain FQDN Required
- Domain FQDN Invalid
- Domain Not Available
- Domain With Too Many Subdomains
- Domain Needs Verification
- User Does Not Exist
If domain needs verification, follow instructions described in List Domain Tokens section.
7.4. Update Domain
POST /api/v1/domains/{ref}
URL parameters:
- ref: domain reference, can be domain ID or FQDN
Request body properties:
- fqdn: (string)
- owner_user_id: (string)
- certificate_ignore: (boolean)
- disabled: (boolean)
Response returns Domain resource.
curl -H "X-Key: TOKEN" \
-H "Content-Type: application/json" \
-d '{"disabled":true}' \
https://gopherpit.com/api/v1/domains/project.example.com
{
"id": "rv3npp3e9yr8kghrjaxzzc9shd2yav2pa92n6k95",
"fqdn": "project.example.com",
"owner_user_id": "xpvzcny34b5jv69eyfd72bz4f4",
"disabled": true
}
Errors:
- Bad Request
- Forbidden
- Domain Not Found
- Domain Already Exists
- Domain FQDN Invalid
- Domain Not Available
- Domain With Too Many Subdomains
- Domain Needs Verification
- User Does Not Exist
If domain needs verification, follow instructions described in List Domain Tokens section.
7.5. Delete Domain
DELETE /api/v1/domains/{ref}
URL parameters:
- ref: domain reference, can be domain ID or FQDN
Response returns Domain response that has been deleted.
curl -H "X-Key: TOKEN" \
-X DELETE \
https://gopherpit.com/api/v1/domains/project.example.com
{
"id": "rv3npp3e9yr8kghrjaxzzc9shd2yav2pa92n6k95",
"fqdn": "project.example.com",
"owner_user_id": "xpvzcny34b5jv69eyfd72bz4f4",
"disabled": true
}
Errors:
7.6. List Domain Tokens
This API call provides information to verify the ownership of a domain.
Domain verification is done by setting a TXT DNS record for one of DNS records provided in the response. The value of the record is provided in the token field.
GET /api/v1/domains/{fqdn}/tokens
URL parameters:
- fqdn: fully qualified domain name
Response returns Domain Tokens resource.
curl -H "X-Key: TOKEN" \
https://gopherpit.com/api/v1/domains/project.example.com/tokens
{
"tokens": [
{
"fqdn": "_gopherpit.example.com",
"token": "77e3EZ7UCQDcffzekSKHquXVyqU="
},
{
"fqdn": "_gopherpit.project.example.com",
"token": "5jwJ2BpmiZo4XHJBjAtTwtvzPkQ="
}
]
}
DNS record example for all example.com subdomains:
$ORIGIN example.com.
_gopherpit TXT "77e3EZ7UCQDcffzekSKHquXVyqU="
To verify only project.example.com subdomains:
$ORIGIN project.example.com.
_gopherpit TXT "5jwJ2BpmiZo4XHJBjAtTwtvzPkQ="
Tokens specific for each user. Verification of ownership by one user does not give permission other users to add subdomains. Each user must have a DNS record with a specific token.
Errors:
7.7. List Domain Users
GET /api/v1/domains/{ref}/users
URL parameters:
- ref: domain reference, can be domain ID or FQDN
Response returns Domain Users resource.
curl -H "X-Key: TOKEN" \
https://gopherpit.com/api/v1/domains/project.example.com/users
{
"owner_user_id": "xpvzcny34b5jv69eyfd72bz4f4",
"user_ids": [
"34ddsdyca45634b5jv6ds727as",
"jkndsi333e9dsn7012n423jb31"
]
}
Errors:
7.8. Grant Domain User
POST /api/v1/domains/{ref}/users/{user}
URL parameters:
- ref: domain reference, can be domain ID or FQDN
- user: user identification parameter, can be user ID, username or email
Response returns OK response.
curl -H "X-Key: TOKEN" \
-X POST \
https://gopherpit.com/api/v1/domains/project.example.com/users/634b5jv6ds727as34ddsdyca45
{
"message": "OK",
"code": 200
}
Errors:
7.9. Revoke Domain User
DELETE /api/v1/domains/{ref}/users/{user}
URL parameters:
- ref: domain reference, can be domain ID or FQDN
- user: user identification parameter, can be user ID, username or email
Response returns OK response.
curl -H "X-Key: TOKEN" \
-X DELETE \
https://gopherpit.com/api/v1/domains/project.example.com/users/634b5jv6ds727as34ddsdyca45
{
"message": "OK",
"code": 200
}
Errors:
7.10. List Domain Packages
GET /api/v1/domains/{ref}/packages
URL parameters:
- ref: domain reference, can be domain ID or FQDN
Query parameters:
- start: (string, default: “”) value returned in previous or next response property
- limit: (integer, default: 100) maximal elements in response
Response returns resource:
- packages: (array of Package)
- count: (integer)
- previous: (string, default: “”)
- next: (string, default: “”)
Values from the previous and next fields can be passed as start query parameter to get a previous or next page in the listing.
curl -H "X-Key: TOKEN" \
https://gopherpit.com/api/v1/domains/project.example.com/packages
{
"packages": [
{
"id": "dqn54p1jwvfxhbebd35w59g2h605t9wm5e2eh206",
"domain_id": "ahy4mp0rvbsvpw469fk5debwvegrmqv761g5mafm",
"fqdn": "project.example.com",
"path": "/application",
"vcs": "git",
"ref_type": "branch",
"ref_name": "stable",
"repo_root": "https://git.example.com/me/my-app"
}
{
"id": "dqn54p1jwvfxhbebd35w59g2h605t9wm5e2eh206",
"domain_id": "ahy4mp0rvbsvpw469fk5debwvegrmqv761g5mafm",
"fqdn": "project.example.com",
"path": "/library",
"vcs": "hg",
"repo_root": "ssh://mercurial.example.com/me/my-lib"
}
],
"count": 2
}
Errors:
7.11. Get Package
GET /api/v1/packages/{id}
URL parameters:
- id: package id
Returns Package resource.
curl -H "X-Key: TOKEN" \
https://gopherpit.com/api/v1/packages/dqn54p1jwvfxhbebd35w59g2h605t9wm5e2eh206
{
"id": "dqn54p1jwvfxhbebd35w59g2h605t9wm5e2eh206",
"domain_id": "ahy4mp0rvbsvpw469fk5debwvegrmqv761g5mafm",
"fqdn": "project.example.com",
"path": "/application",
"vcs": "git",
"ref_type": "branch",
"ref_name": "stable",
"repo_root": "https://git.example.com/me/my-app"
}
Errors:
7.12. Add Package
POST /api/v1/packages
Request body properties:
- domain: (string, domain reference, can be domain ID or FQDN)
- path: (string)
- vcs: (string, possible values: “git”, “hg”, “bzr”, “svn”)
- repo_root: (string)
- ref_type: (string, default: “”, possible values: “branch”, “tag”)
- ref_name: (string, default: “”)
- go_source: (string, default: “”)
- redirect_url: (string, default: “”)
- disabled: (string, default: false)
Response returns Package resource.
curl -H "X-Key: TOKEN" \
-H "Content-Type: application/json" \
-d '{"domain":"project.example.com","path":"/my-app","vcs":"git","repo_root":"https://github.com/me/app"}' \
https://gopherpit.com/api/v1/packages
{
"id": "ghrjaxzzc9shd2yav2pa92n6k95rv3npp3e9yr8k",
"domain_id": "project.example.com",
"path": "/my-app",
"vcs": "git",
"repo_root": "https://github.com/example/my-app"
}
Errors:
- Bad Request
- Forbidden
- Domain Not Found
- Package Already Exists
- Package Domain Required
- Package Path Required
- Package VCS Required
- Package Repository Root Required
- Package Repository Root Invalid
- Package Repository Root Scheme Required
- Package Repository Root Scheme Invalid
- Package Repository Root Host Invalid
- Package Reference Type Invalid
- Package Reference Name Required
- Package Reference Change Rejected
- Package Redirect URL Invalid
7.13. Update Package
POST /api/v1/packages/{id}
URL parameters:
- id: package id
Request body properties:
- domain: (string, domain reference, can be domain ID or FQDN)
- path: (string)
- vcs: (string, possible values: “git”, “hg”, “bzr”, “svn”)
- repo_root: (string)
- ref_type: (string, default: “”, possible values: “branch”, “tag”)
- ref_name: (string, default: “”)
- go_source: (string, default: “”)
- redirect_url: (string, default: “”)
- disabled: (string, default: false)
Response returns Package resource.
curl -H "X-Key: TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"/our-app","disabled":true}' \
https://gopherpit.com/api/v1/packages
{
"id": "ghrjaxzzc9shd2yav2pa92n6k95rv3npp3e9yr8k",
"domain_id": "project.example.com",
"path": "/our-app",
"vcs": "git",
"repo_root": "https://github.com/example/my-app",
"disabled": true
}
Errors:
- Bad Request
- Forbidden
- Domain Not Found
- Package Not Found
- Package Already Exists
- Package Domain Required
- Package Path Required
- Package VCS Required
- Package Repository Root Required
- Package Repository Root Invalid
- Package Repository Root Scheme Required
- Package Repository Root Scheme Invalid
- Package Repository Root Host Invalid
- Package Reference Type Invalid
- Package Reference Name Required
- Package Reference Change Rejected
- Package Redirect URL Invalid
7.14. Delete Package
DELETE /api/v1/packages/{id}
URL parameters:
- id: package id
Response returns Package resource that has been deleted.
curl -H "X-Key: TOKEN" \
-X DELETE \
https://gopherpit.com/api/v1/packages/ghrjaxzzc9shd2yav2pa92n6k95rv3npp3e9yr8k
{
"id": "ghrjaxzzc9shd2yav2pa92n6k95rv3npp3e9yr8k",
"domain_id": "project.example.com",
"path": "/our-app",
"vcs": "git",
"repo_root": "https://github.com/example/my-app",
"disabled": true
}
Errors:
8. API Status Codes
API utilizes HTTP Status codes as well as specific codes for more granular error reporting.
Message responses have the following example of JSON-encoded body:
{
"message": "Domain Not Found",
"code": 1000
}