README.md 1.4 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.

Ben Boeckel's avatar
Ben Boeckel committed
6
The API is based off of the 8.16.0 API and will likely aggressively track new
Ben Boeckel's avatar
Ben Boeckel committed
7
8
9
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
10
All API types should be implemented in the [types](src/types.rs.in) module.
Ben Boeckel's avatar
Ben Boeckel committed
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
These types should generally be implemented based on the `lib/api/entities.rb`
module in the Gitlab repository. However, in the interest of usability,
entities may be combined using `Option` to handle the differences. Generally,
this should be done where the difference is "small". As a concrete example, the
`Project` entity has dozens of fields and `ProjectWithAccess` has one
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.

# 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.