Skip to content
This repository was archived by the owner on Jan 26, 2023. It is now read-only.

Commit db8b5c1

Browse files
raphaelhuefnerraphaelhuefner
committed
document API in README
1 parent a2a6cca commit db8b5c1

File tree

1 file changed

+189
-8
lines changed

1 file changed

+189
-8
lines changed

‎README.md

Lines changed: 189 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,210 @@
1-
# python-api-client
2-
Python API Client
1+
# Gitcoin Python API Client
2+
3+
This Python package provides the `bounties` endpoint of the Gitcoin API, which allows you to:
4+
5+
- list all bounties
6+
- list all bounties which meet certain conditions (i.e. filter them)
7+
- retrieve a single bounty by it's primary key
38

49
## Install via pypi
510

611
```bash
712
pip install gitcoin
813
```
914

10-
## Usage
15+
## Usage Examples
16+
17+
### List all bounties
18+
19+
```python
20+
from gitcoin import Gitcoin
21+
api = Gitcoin()
22+
all_bounties = api.bounties.all()
23+
```
24+
25+
### List all open bounties
26+
27+
```python
28+
from gitcoin import Gitcoin
29+
api = Gitcoin()
30+
open_bounties = api.bounties.filter(is_open=True).all()
31+
```
32+
33+
### List all open "Beginner" bounties
34+
35+
```python
36+
from gitcoin import Gitcoin
37+
api = Gitcoin()
38+
bounties_api = api.bounties
39+
bounties_api.filter(is_open=True)
40+
bounties_api.filter(experience_level='Beginner')
41+
open_beginner_bounties = bounties_api.all()
42+
```
43+
44+
The example above has been reformatted for easier reading. A [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface#Python) is also available. Please scroll the following code block all the way to the end to see the whole line:
45+
46+
```python
47+
from gitcoin import Gitcoin
48+
api = Gitcoin()
49+
open_beginner_bounties = api.bounties.filter(is_open=True, experience_level='Beginner').all()
50+
```
51+
52+
### List all open bounties marked for either "Beginner" OR "Intermediate" experience level
53+
54+
For some filter conditions, multiple different values can be given, which results in a logical `OR` for that condition:
1155

1256
```python
1357
from gitcoin import Gitcoin
1458
api = Gitcoin()
15-
api.bounties.all()
16-
api.bounties.filter(pk__gt=100).all()
59+
bounties_api = api.bounties
60+
bounties_api.filter(is_open=True)
61+
bounties_api.filter(experience_level='Beginner')
62+
bounties_api.filter(experience_level='Intermediate')
63+
open_beginner_and_intermediate_bounties = bounties_api.all()
64+
```
65+
66+
The example above has been reformatted for easier reading. A [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface#Python) is also available. Please scroll the following code block all the way to the end to see the whole line:
67+
68+
```python
69+
from gitcoin import Gitcoin
70+
api = Gitcoin()
71+
open_beginner_and_intermediate_bounties = api.bounties.filter(is_open=True).filter(experience_level='Beginner').filter(experience_level='Intermediate').all()
1772
```
1873

1974
## API
2075

21-
### public (unrestricted)
76+
### Instantiation
77+
78+
1. Create a `Gitcoin()` API root object:
79+
```python
80+
from gitcoin import Gitcoin
81+
api = Gitcoin()
82+
```
83+
2. The `bounties` API endpoint is accessible as a property of the API root object:
84+
```python
85+
bounties_endpoint = api.bounties
86+
```
87+
Each access to the `bounties` property results in a new `Endpoint` object with no filter conditions or any other parameters (like sorting) set. If you want to keep a specific set of filter conditions, simply store the `Endpoint` object in a variable instead of referring to the `bounties` property of the root object.
88+
89+
### `bounties.filter(**kwargs)`
90+
91+
Limit the list of bounties returned by either `get_page()` or `all()` to those bounties meeting the filter condition(s). For some filter conditions, multiple different values can be given, which results in a logical `OR` for that condition.
92+
93+
The condition name is the name of the keyword argument, and the condition value is the value of the keyword argument:
94+
95+
```python
96+
open_bounties = api.bounties.filter(is_open=True).all()
97+
```
98+
99+
Conditions with different names can be given in one `filter()` call:
100+
101+
```python
102+
open_beginner bounties = api.bounties.filter(is_open=True, experience_level='Beginner').all()
103+
```
104+
105+
Or if preferred, they can also be given in separate `filter()` calls:
106+
107+
```python
108+
open_beginner bounties = api.bounties.filter(is_open=True).filter(experience_level='Beginner').all()
109+
```
110+
111+
Giving multiple values for the same filter condition has to be done in separate calls to `filter()`:
112+
113+
```python
114+
beginner_and_intermediate_bounties = api.bounties.filter(experience_level='Beginner').filter(experience_level='Intermediate').all()
115+
```
116+
117+
For the following filter conditions, multiple values can be given to achieve a logical `OR`:
118+
119+
- `experience_level (str)`
120+
- `project_length (str)`
121+
- `bounty_type (str)`
122+
- `bounty_owner_address (str)`
123+
- `bounty_owner_github_username (str)`
124+
- `idx_status (str)`
125+
- `network (str)`
126+
- `standard_bounties_id (int)`
127+
- `github_url (str)`
128+
- `raw_data (str)`
129+
130+
The following filter conditions are **single value**, in other words, multiple values result in the last value overwriting all earlier values:
131+
132+
- `pk__gt (int)`
133+
- `started (str)`
134+
- `is_open (bool)`
135+
- `fulfiller_github_username (str)`
136+
- `interested_github_username (str)`
137+
138+
`filter()` returns the `Endpoint` object itself to enable a [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface#Python).
139+
140+
### `bounties.order_by(sort)`
141+
142+
Determine the order of the bounties returned by either `get_page()` or `all()`. The `sort` argument is a `string` containing a DB field name to sort by. It can also have an optional "-" prefix for reversing the direction. Choose from these field names:
143+
144+
- `accepted`
145+
- `balance`
146+
- `bounty_owner_address`
147+
- `bounty_owner_email`
148+
- `bounty_owner_github_username`
149+
- `bounty_owner_name`
150+
- `bounty_type`
151+
- `canceled_on`
152+
- `contract_address`
153+
- `current_bounty`
154+
- `experience_level`
155+
- `expires_date`
156+
- `fulfillment_accepted_on`
157+
- `fulfillment_started_on`
158+
- `fulfillment_submitted_on`
159+
- `github_comments`
160+
- `github_url`
161+
- `idx_experience_level`
162+
- `idx_project_length`
163+
- `idx_status`
164+
- `interested`
165+
- `interested_comment`
166+
- `is_open`
167+
- `issue_description`
168+
- `last_comment_date`
169+
- `metadata`
170+
- `network`
171+
- `num_fulfillments`
172+
- `override_status`
173+
- `privacy_preferences`
174+
- `project_length`
175+
- `raw_data`
176+
- `snooze_warnings_for_days`
177+
- `standard_bounties_id`
178+
- `submissions_comment`
179+
- `title`
180+
- `token_address`
181+
- `token_name`
182+
- `token_value_in_usdt`
183+
- `token_value_time_peg`
184+
- `_val_usd_db`
185+
- `value_in_eth`
186+
- `value_in_token`
187+
- `value_in_usdt`
188+
- `value_in_usdt_now`
189+
- `value_true`
190+
- `web3_created`
191+
- `web3_type`
192+
193+
`order_by()` returns the `Endpoint` object itself to enable a [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface#Python).
194+
195+
### `bounties.get_page(number=1, per_page=25)`
196+
197+
Returns one page of the (potentially `filter()`ed) `list` of bounties with the given 1-based index `number (int)`. The page size can be set with `per_page (int)`. Each bounty is a `dict`, basically the direct output of [`requests`' `.json()`](http://docs.python-requests.org/en/master/user/quickstart/#json-response-content) call.
198+
199+
### `bounties.all()`
200+
201+
Returns the complete (potentially `filter()`ed) `list` of bounties. Each bounty is a `dict`, basically the direct output of [`requests`' `.json()`](http://docs.python-requests.org/en/master/user/quickstart/#json-response-content) call.
22202

23-
`GET /api/v2/bounties`
203+
### `bounties.get(primary_key)`
24204

25-
### private (restricted)
205+
Returns one (1) bounty as specified by `primary_key (int)`. It is returned as a `dict`, basically the direct output of [`requests`' `.json()`](http://docs.python-requests.org/en/master/user/quickstart/#json-response-content) call.
26206

207+
-------------------------
27208

28209
## Todo
29210

0 commit comments

Comments
 (0)