README.md 3.92 KB
Newer Older
Ben Boeckel's avatar
Ben Boeckel committed
1
2
3
4
5
# Gitlab API

This library implements an interface to communicate with a Gitlab instance. Not
all API endpoints are implemented, but patches are welcome.

Brad King's avatar
Brad King committed
6
The API is based off of the GitLab 13.10 API v4 and will likely aggressively track
7
8
9
new API additions, so not all available parameters or types will support
arbitrarily old GitLab instances (usually query parameters will be ignored and
type fields cause deserialization errors).
Ben Boeckel's avatar
Ben Boeckel committed
10

11
12
13
14
15
The endpoints that are supported all live under the [`api`](src/api.rs) module.
Each endpoint may be constructed using a "builder" pattern to provide supported
fields. To use an endpoint, you may query it using the
[`Query`](src/api/query.rs) trait. There are additional helpers to handle
different cases:
Ben Boeckel's avatar
Ben Boeckel committed
16

17
18
19
20
21
22
23
24
  - [`api::ignore`](src/api/ignore.rs): Ignore the GitLab response (useful for
    `POST` or `PUT` endpoints).
  - [`api::paged`](src/api/paged.rs): Fetch results that are paginated.
  - [`api::raw`](src/api/raw.rs): Return the raw data from GitLab instead of
    deserializing into a structure.
  - [`api::sudo`](src/api/sudo.rs): Modify an endpoint using GitLab's `sudo`
    parameter for masquerading as another user (requires an administrator
    token).
Ben Boeckel's avatar
Ben Boeckel committed
25

26
27
28
29
30
All endpoints return data types of the caller's choosing that implement
`serde`'s `Deserialize` trait. Callers should define their own structures for
obtaining data from the API. This allows the structure to be more easily
changeable for different GitLab versions (rather than this crate being pinned
to a given version).
Ben Boeckel's avatar
Ben Boeckel committed
31

32
33
34
35
36
# Versioning

Since this crate follows Gitlab upstream, semantic versioning may not be
possible. Instead, the crate uses the following versioning scheme:

Brad King's avatar
Brad King committed
37
  * Gitlab 13.10 support → 0.1310.x
Brad King's avatar
Brad King committed
38
  * Gitlab 13.9 support → 0.1309.x
Brad King's avatar
Brad King committed
39
  * Gitlab 13.8 support → 0.1308.x
Brad King's avatar
Brad King committed
40
  * Gitlab 13.7 support → 0.1307.x
Brad King's avatar
Brad King committed
41
  * Gitlab 13.6 support → 0.1306.x
Brad King's avatar
Brad King committed
42
  * Gitlab 13.5 support → 0.1305.x
Brad King's avatar
Brad King committed
43
  * Gitlab 13.4 support → 0.1304.x
Brad King's avatar
Brad King committed
44
  * Gitlab 13.3 support → 0.1303.x
Brad King's avatar
Brad King committed
45
  * Gitlab 13.2 support → 0.1302.x
Brad King's avatar
Brad King committed
46
  * Gitlab 13.1 support → 0.1301.x
Ben Boeckel's avatar
Ben Boeckel committed
47
  * Gitlab 13.0 support → 0.1300.x
Brad King's avatar
Brad King committed
48
  * Gitlab 12.10 support → 0.1210.x
Brad King's avatar
Brad King committed
49
  * Gitlab 12.9 support → 0.1209.x
Brad King's avatar
Brad King committed
50
  * Gitlab 12.8 support → 0.1208.x
Brad King's avatar
Brad King committed
51
  * Gitlab 12.7 support → 0.1207.x
Brad King's avatar
Brad King committed
52
  * Gitlab 12.6 support → 0.1206.x
Brad King's avatar
Brad King committed
53
  * Gitlab 12.5 support → 0.1205.x
Brad King's avatar
Brad King committed
54
  * Gitlab 12.4 support → 0.1204.x
Brad King's avatar
Brad King committed
55
  * Gitlab 12.3 support → 0.1203.x
Brad King's avatar
Brad King committed
56
  * Gitlab 12.2 support → 0.1202.x
Brad King's avatar
Brad King committed
57
  * Gitlab 12.1 support → 0.1201.x
Brad King's avatar
Brad King committed
58
  * Gitlab 12.0 support → 0.1200.x
Brad King's avatar
Brad King committed
59
  * Gitlab 11.11 support → 0.1111.x
Brad King's avatar
Brad King committed
60
  * Gitlab 11.10 support → 0.1110.x
Brad King's avatar
Brad King committed
61
  * Gitlab 11.9 support → 0.1109.x
Brad King's avatar
Brad King committed
62
  * Gitlab 11.8 support → 0.1108.x
Brad King's avatar
Brad King committed
63
  * Gitlab 11.7 support → 0.1107.x
Brad King's avatar
Brad King committed
64
  * Gitlab 11.6 support → 0.1106.x
Brad King's avatar
Brad King committed
65
  * Gitlab 11.5 support → 0.1105.x
Brad King's avatar
Brad King committed
66
  * Gitlab 11.4 support → 0.1104.x
Brad King's avatar
Brad King committed
67
  * Gitlab 11.3 support → 0.1103.x
Brad King's avatar
Brad King committed
68
  * Gitlab 11.2 support → 0.1102.x
Brad King's avatar
Brad King committed
69
  * Gitlab 11.1 support → 0.1101.x
Brad King's avatar
Brad King committed
70
  * Gitlab 11.0 support → 0.1100.x
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
  * Gitlab 10.8 support → 0.1008.x
  * Gitlab 10.7 support → 0.1007.x
  * Gitlab 10.6 support → 0.1006.x
  * Gitlab 10.5 support → 0.1005.x
  * Gitlab 10.4 support → 0.1004.x
  * Gitlab 10.3 support → 0.1003.x
  * Gitlab 10.2 support → 0.1002.x
  * Gitlab 10.1 support → 0.1001.x
  * Gitlab 10.0 support → 0.1000.x
  * Gitlab 9.5 support → 0.905.x
  * Gitlab 9.4 support → 0.904.x
  * Gitlab 9.3 support → 0.903.x
  * Gitlab 9.2 support → 0.902.x
  * Gitlab 9.1 support → 0.901.x
  * Gitlab 9.0 support → 0.900.x
  * Gitlab 8.17 support → 0.817.x
  * Gitlab 8.16 support → 0.816.x
88
89
90
91
92
93

Minor versions may fix bugs, add API endpoint bindings, or improve webhook
coverage. It is recommended to depend on the full version of the crate since
types may change in patch-level updates in order to match Gitlab's interface:

```toml
Brad King's avatar
Brad King committed
94
gitlab = "=0.1310.0"
95
96
```

Ben Boeckel's avatar
Ben Boeckel committed
97
98
99
100
101
# API bugs

Sometimes, the API will return `null` for fields that have been added after the
entry was created. In these cases, mark the field as an `Option` with a comment
describing why it is so.