README.md 3.63 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.2 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.2 support → 0.1302.x
Brad King's avatar
Brad King committed
38
  * Gitlab 13.1 support → 0.1301.x
Ben Boeckel's avatar
Ben Boeckel committed
39
  * Gitlab 13.0 support → 0.1300.x
Brad King's avatar
Brad King committed
40
  * Gitlab 12.10 support → 0.1210.x
Brad King's avatar
Brad King committed
41
  * Gitlab 12.9 support → 0.1209.x
Brad King's avatar
Brad King committed
42
  * Gitlab 12.8 support → 0.1208.x
Brad King's avatar
Brad King committed
43
  * Gitlab 12.7 support → 0.1207.x
Brad King's avatar
Brad King committed
44
  * Gitlab 12.6 support → 0.1206.x
Brad King's avatar
Brad King committed
45
  * Gitlab 12.5 support → 0.1205.x
Brad King's avatar
Brad King committed
46
  * Gitlab 12.4 support → 0.1204.x
Brad King's avatar
Brad King committed
47
  * Gitlab 12.3 support → 0.1203.x
Brad King's avatar
Brad King committed
48
  * Gitlab 12.2 support → 0.1202.x
Brad King's avatar
Brad King committed
49
  * Gitlab 12.1 support → 0.1201.x
Brad King's avatar
Brad King committed
50
  * Gitlab 12.0 support → 0.1200.x
Brad King's avatar
Brad King committed
51
  * Gitlab 11.11 support → 0.1111.x
Brad King's avatar
Brad King committed
52
  * Gitlab 11.10 support → 0.1110.x
Brad King's avatar
Brad King committed
53
  * Gitlab 11.9 support → 0.1109.x
Brad King's avatar
Brad King committed
54
  * Gitlab 11.8 support → 0.1108.x
Brad King's avatar
Brad King committed
55
  * Gitlab 11.7 support → 0.1107.x
Brad King's avatar
Brad King committed
56
  * Gitlab 11.6 support → 0.1106.x
Brad King's avatar
Brad King committed
57
  * Gitlab 11.5 support → 0.1105.x
Brad King's avatar
Brad King committed
58
  * Gitlab 11.4 support → 0.1104.x
Brad King's avatar
Brad King committed
59
  * Gitlab 11.3 support → 0.1103.x
Brad King's avatar
Brad King committed
60
  * Gitlab 11.2 support → 0.1102.x
Brad King's avatar
Brad King committed
61
  * Gitlab 11.1 support → 0.1101.x
Brad King's avatar
Brad King committed
62
  * Gitlab 11.0 support → 0.1100.x
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
  * 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
80 81 82 83 84 85

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
Ben Boeckel's avatar
Ben Boeckel committed
86
gitlab = "=0.1302.1"
87 88
```

Ben Boeckel's avatar
Ben Boeckel committed
89 90 91 92 93
# 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.