mirror of
https://github.com/gogs/gogs.git
synced 2026-02-08 23:47:02 +01:00
117 lines
3.4 KiB
Plaintext
117 lines
3.4 KiB
Plaintext
---
|
|
title: "Introduction"
|
|
sidebarTitle: "Introduction"
|
|
description: "Overview of the Gogs API including authentication, pagination, and schema"
|
|
---
|
|
|
|
The Gogs API provides a RESTful interface for interacting with your Gogs instance programmatically. It aims to follow a format similar to the [GitHub REST API v3](https://developer.github.com/v3/).
|
|
|
|
<Info>
|
|
The API is bundled with every Gogs installation. No additional setup is required.
|
|
</Info>
|
|
|
|
<Warning>
|
|
The API is still in its early stages. Content and endpoints are subject to change.
|
|
</Warning>
|
|
|
|
## Current version
|
|
|
|
All Gogs APIs are under **v1** using the request path prefix `/api/v1`.
|
|
|
|
```
|
|
https://gogs.example.com/api/v1
|
|
```
|
|
|
|
## Schema
|
|
|
|
All data is sent and received as **JSON** unless specified otherwise.
|
|
|
|
```http
|
|
HTTP/2 200
|
|
Content-Type: application/json; charset=UTF-8
|
|
```
|
|
|
|
All timestamps are returned in **RFC 3339** format:
|
|
|
|
```
|
|
YYYY-MM-DDTHH:MM:SSZ
|
|
2006-01-02T15:04:05Z07:00
|
|
```
|
|
|
|
## Authentication
|
|
|
|
There are two ways to authenticate through the Gogs API. Requests that require authentication will return `404 Not Found` instead of `403 Forbidden` in some places. This is to prevent the accidental leakage of private resources to unauthorized users.
|
|
|
|
<Tabs>
|
|
<Tab title="Basic authentication">
|
|
Basic authentication is used to obtain access tokens. Supply your username (you will be prompted for your password):
|
|
|
|
```bash
|
|
curl -u "alice" https://gogs.example.com/api/v1/users/alice/tokens
|
|
```
|
|
|
|
<Warning>
|
|
Basic authentication should only be used to generate access tokens. Do not use it for regular API requests.
|
|
</Warning>
|
|
</Tab>
|
|
<Tab title="Access token">
|
|
Personal access tokens are the recommended way to authenticate. They can be sent via a request **header** or a **URL query parameter**.
|
|
|
|
**Using a header:**
|
|
|
|
```bash
|
|
curl -H "Authorization: token {YOUR_ACCESS_TOKEN}" https://gogs.example.com/api/v1/user/repos
|
|
```
|
|
|
|
**Using a query parameter:**
|
|
|
|
```bash
|
|
curl https://gogs.example.com/api/v1/user/repos?token={YOUR_ACCESS_TOKEN}
|
|
```
|
|
|
|
<Tip>
|
|
Using the `Authorization` header is preferred over the query parameter, as URLs may be logged by proxies and servers.
|
|
</Tip>
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## Pagination
|
|
|
|
API responses that return multiple items are paginated. You can specify further pages with the `?page` query parameter.
|
|
|
|
```bash
|
|
curl https://gogs.example.com/api/v1/repos/alice/hello/issues?page=1
|
|
```
|
|
|
|
Page numbering is **1-based**. Omitting the `?page` parameter returns the first page.
|
|
|
|
### Link header
|
|
|
|
Pagination info is included in the [Link header](http://tools.ietf.org/html/rfc5988) of each response. Use this to navigate between pages programmatically.
|
|
|
|
```http
|
|
Link: <https://gogs.example.com/api/v1/repos/alice/hello/issues?page=3>; rel="next",
|
|
<https://gogs.example.com/api/v1/repos/alice/hello/issues?page=50>; rel="last"
|
|
```
|
|
|
|
The possible `rel` values are:
|
|
|
|
| Name | Description |
|
|
|---|---|
|
|
| `next` | The link relation for the immediate next page of results. |
|
|
| `last` | The link relation for the last page of results. |
|
|
| `first` | The link relation for the first page of results. |
|
|
| `prev` | The link relation for the immediate previous page of results. |
|
|
|
|
<Tip>
|
|
Always use the Link header values to navigate between pages rather than constructing URLs manually.
|
|
</Tip>
|
|
|
|
## SDKs
|
|
|
|
The following best-effort-maintained SDKs are available:
|
|
|
|
| Language | Repository |
|
|
|---|---|
|
|
| Go | [gogs/go-gogs-client](https://github.com/gogs/go-gogs-client) |
|