README.md 2.96 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 12.2 API v4 and will likely aggressively track
Ben Boeckel's avatar
Ben Boeckel committed
7
8
new API additions, so the newest release may not support talking to older
releases where fields have been added.
Ben Boeckel's avatar
Ben Boeckel committed
9

Ben Boeckel's avatar
Ben Boeckel committed
10
11
All API types should be implemented in the [types](src/types.rs) module. These
types should generally be implemented based on the `lib/api/entities.rb`
Ben Boeckel's avatar
Ben Boeckel committed
12
13
module in the Gitlab repository. However, in the interest of usability,
entities may be combined using `Option` to handle the differences. Generally,
Ben Boeckel's avatar
Ben Boeckel committed
14
15
this should be done where the difference is "small". As a concrete example,
the `Project` entity has dozens of fields and `ProjectWithAccess` has one
Ben Boeckel's avatar
Ben Boeckel committed
16
17
18
19
20
21
22
23
24
25
additional field (`permissions`) which is added using `Option` rather than
creating a new `ProjectWithAccess` structure which only differs in this field.

In short, map the API as close as possible, but also know when to bend the
rules.

If you run into places where Gitlab dumps a JSON value rather than an actual
entity, please consider updating upstream to use a real entity so that changes
to the structure are easier to track.

26
27
28
29
30
# 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
31
  * Gitlab 12.2 support → 0.1202.x
Brad King's avatar
Brad King committed
32
  * Gitlab 12.1 support → 0.1201.x
Brad King's avatar
Brad King committed
33
  * Gitlab 12.0 support → 0.1200.x
Brad King's avatar
Brad King committed
34
  * Gitlab 11.11 support → 0.1111.x
Brad King's avatar
Brad King committed
35
  * Gitlab 11.10 support → 0.1110.x
Brad King's avatar
Brad King committed
36
  * Gitlab 11.9 support → 0.1109.x
Brad King's avatar
Brad King committed
37
  * Gitlab 11.8 support → 0.1108.x
Brad King's avatar
Brad King committed
38
  * Gitlab 11.7 support → 0.1107.x
Brad King's avatar
Brad King committed
39
  * Gitlab 11.6 support → 0.1106.x
Brad King's avatar
Brad King committed
40
  * Gitlab 11.5 support → 0.1105.x
Brad King's avatar
Brad King committed
41
  * Gitlab 11.4 support → 0.1104.x
Brad King's avatar
Brad King committed
42
  * Gitlab 11.3 support → 0.1103.x
Brad King's avatar
Brad King committed
43
  * Gitlab 11.2 support → 0.1102.x
Brad King's avatar
Brad King committed
44
  * Gitlab 11.1 support → 0.1101.x
Brad King's avatar
Brad King committed
45
  * Gitlab 11.0 support → 0.1100.x
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
  * 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
63
64
65
66
67
68

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
69
gitlab = "=0.1202.0"
70
71
```

Ben Boeckel's avatar
Ben Boeckel committed
72
73
74
75
76
# 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.