API v1 - GoChallenge/gochallenge GitHub Wiki

Authentication

Currently we only support one way to authenticate through API v1.

API Key (sent in a header)

$ curl -H "Auth-ApiKey: API_KEY" https://golang-challenge.com/

Requests that require authentication will return 401 Unauthorized if invalid API_KEY is given.

Endpoints

Get current challenge

This returns the latest open challenge.

GET /v1/challenges/current

Response

{
	"id": 1,
	"url": "https://golang-challenge.com/challenges/1",
	"status": "open",
	"import": "https://git.golang-challenge.com/code/challenge-001",
	"author":{"name":"Jane Doe"},
	"name":"The Go Challenge 1",
	"start":"2015-03-01T00:00:00Z",
	"end":"2015-03-14T00:00:00Z"
}

where values are

Name Type Description
url string public web page of the challenge
status string current status of the challenge - unreleased, open or closed
import string url where the setup code is available (can be fed into go get tool)
author object author's details
name string full name of the challenge
start time start time
end time end time

Get a single challenge

GET /v1/challenges/:challenge_id

Response

same as for the current challenge above

List challenges

List all challenges. This endpoint MAY use authentication data. If no authentication data is provided, only publicly available challenges are returned. Otherwise, the list may include challenges which are not currently public, if authenticated user has a higher level of access.

GET /v1/challenges

Parameters

Name Type Description
status string Indicates the status of the challenges to return. Can be either: open, closed, or all. Default to open.

Response

[
	{
		"id": 1,
		"url": "https://golang-challenge.com/challenges/1",
		"status": "open",
		...
	},
	...
]

If user has limited access level, the list must contain only challenges visible to the user - e.g. participants should not be able to see future challenges until they're live.

See below for detailed description of challenge structure.

Create a submission

This endpoint requires authentication.

POST /v1/challenges/:challenge_id/submission

Content-type: multipart/related; boundary=foo_bar_baz
```

### Input
Say, `--foo_bar_baz` being the boundary
```
--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
    "type": "normal",
}

--foo_bar_baz
Content-Type: application/octet-stream

<zip data>
--foo_bar_baz--
```

### Response
```
{
     "id": "de305d54-75b4-431b-adb2-eb6b9e546013",
     "url": "https://golang-challenge.com/challenges/1/submissions/de305d54-75b4-431b-adb2-eb6b9e546013/",
     "type": "normal",
     "challenge_id": 1,
     "created": "2010-04-14T02:15:15Z",
}
```
**Clients should not make any assumptions of ID being included in the URL verbatim**

<a name="list-submissions-on-a-challenge"></a>
## List submissions on a challenge

```
GET /v1/challenges/:challenge_id/submissions
```

### Response

```
[
	{
		"id": "de305d54-75b4-431b-adb2-eb6b9e546013",
		"url": "https://golang-challenge.com/challenges/1/submissions/de305d54-75b4-431b-adb2-eb6b9e546013/",
		"created": "2010-04-14T02:15:15Z",
		...
	},
	...
]
```

<a name="download-submission-code"></a>
## Download submission code

```
GET /v1/submissions/:submission_id/download
```

### Input

None

### Response

Code of the requested submission is being sent back as an attached content (`Content-Type: attachment`).

<a name="delete-a-submission"></a>
## Delete a submission

This endpoint requires authentication.

```
DELETE /v1/submissions/:submission_id
```

### Response

```
Status: 204 No Content
```

<a name="list-of-challenge-winners"></a>
## List of challenge winners

```
GET /v1/challenges/:challenge_id/winners
```

## Response

```
[
	{
		"submission_id": 2,
		"reviewer_comments": [
			{
				"name": "Reviewer Name",
				"comment": "",
				...
			},
			...
		]
	},
	...
]
```
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️