Skip to content

Commit be9956f

Browse files
myroslavmyroslav
committed
First cut of tutorial
1 parent c6d33e0 commit be9956f

1 file changed

Lines changed: 338 additions & 0 deletions

File tree

‎docs/source/tutorial.rst‎

Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,341 @@
33
Tutorial
44
========
55

6+
Let's try exploring the `/tenders` endpoint::
7+
8+
curl -v http://api-sandbox.openprocurement.org/api/0/tenders
9+
> GET /api/0/tenders HTTP/1.1
10+
> Host: api-sandbox.openprocurement.org
11+
>
12+
< HTTP/1.1 200 OK
13+
< Content-Type: application/json; charset=UTF-8
14+
<
15+
{
16+
"data": []
17+
}
18+
19+
Just invoking it reveals empty set.
20+
21+
Now let's attempt creating some tender::
22+
23+
curl -v -X POST http://api-sandbox.openprocurement.org/api/0/tenders
24+
> POST /api/0/tenders HTTP/1.1
25+
> Host: api-sandbox.openprocurement.org
26+
>
27+
< HTTP/1.1 415 Unsupported Media Type
28+
< Content-Type: application/json; charset=UTF-8
29+
<
30+
{
31+
"status": "error",
32+
"errors": [
33+
{
34+
"location": "header",
35+
"name": "Content-Type",
36+
"description": "Content-Type header should be one of ['application\/json']"
37+
}
38+
]
39+
}
40+
41+
Error states that only accepted Content-Type is `application/json`.
42+
43+
Let's satisfy the Content-type requirement::
44+
45+
curl -v -H "Content-Type: application/json" -X POST http://api-sandbox.openprocurement.org/api/0/tenders
46+
> POST /api/0/tenders HTTP/1.1
47+
> Host: api-sandbox.openprocurement.org
48+
> Content-Type: application/json
49+
>
50+
< HTTP/1.1 422 Unprocessable Entity
51+
< Content-Type: application/json; charset=UTF-8
52+
<
53+
{
54+
"status": "error",
55+
"errors": [
56+
{
57+
"location": "body",
58+
"name": "data",
59+
"description": "No JSON object could be decoded"
60+
}
61+
]
62+
}
63+
64+
Error states that no `data` found in JSON body.
65+
66+
Let's provide the data attribute in the body submitted::
67+
68+
curl -v -H "Content-Type: application/json" -X POST --data @data.json http://api-sandbox.openprocurement.org/api/0/tenders
69+
> POST /api/0/tenders HTTP/1.1
70+
> Host: api-sandbox.openprocurement.org
71+
> Content-Type: application/json
72+
>
73+
> {
74+
> "data":{}
75+
> }
76+
77+
< HTTP/1.1 201 Created
78+
< Content-Type: application/json; charset=UTF-8
79+
< Location: http://api-sandbox.openprocurement.org/api/0/tenders/be40e257812044f3913534cc537d1f99
80+
<
81+
{
82+
"data": {
83+
"id": "be40e257812044f3913534cc537d1f99",
84+
"tenderID": "UA-be40e257812044f3913534cc537d1f99",
85+
"modified": "2014-10-25T00:24:12.772078"
86+
}
87+
}
88+
89+
Success! Now we can see that new object was created. Response code is `201` and `Location` response header reports the location of object created. The body of response reveals the information about tender created, its internal `id` (that matches the `Location` segment), its official `tenderID` and `modified` datestamp stating the moment in time when tender was last modified.
90+
91+
Let's access the URL of object created (the `Location` header of the response)::
92+
93+
curl -v http://api-sandbox.openprocurement.org/api/0/tenders/be40e257812044f3913534cc537d1f99
94+
> GET /api/0/tenders/be40e257812044f3913534cc537d1f99 HTTP/1.1
95+
> Host: api-sandbox.openprocurement.org
96+
>
97+
< HTTP/1.1 200 OK
98+
< Content-Type: application/json; charset=UTF-8
99+
<
100+
{
101+
"data": {
102+
"id": "be40e257812044f3913534cc537d1f99",
103+
"tenderID": "UA-be40e257812044f3913534cc537d1f99",
104+
"modified": "2014-10-25T00:24:12.772078"
105+
}
106+
}
107+
108+
We can see the same response we got after creating tender.
109+
110+
Let's see what listing of tenders reveals us::
111+
112+
curl -v http://api-sandbox.openprocurement.org/api/0/tenders/
113+
> GET /api/0/tenders/ HTTP/1.1
114+
> Host: api-sandbox.openprocurement.org
115+
>
116+
< HTTP/1.1 200 OK
117+
< Content-Type: application/json; charset=UTF-8
118+
<
119+
{
120+
"data": [
121+
{
122+
"id": "be40e257812044f3913534cc537d1f99",
123+
"modified": "2014-10-25T00:24:12.772078"
124+
}
125+
]
126+
}
127+
128+
We do see the internal `id` of a tender (that can be used to construct full URL by prepending `http://api-sandbox.openprocurement.org/api/0/tenders/`) and its `modified` datestamp.
129+
130+
Let's try creating tender with more data, passing the `procuringEntity` of a tender::
131+
132+
curl -v -H "Content-Type: application/json" --data @tender.json -X POST http://api-sandbox.openprocurement.org/api/0/tenders
133+
> POST /api/0/tenders HTTP/1.1
134+
> Host: api-sandbox.openprocurement.org
135+
> Content-Type: application/json
136+
>
137+
> {
138+
> "data":{
139+
> "procuringEntity": {
140+
> "id": {
141+
> "name": "Заклад \"Загальноосвітня школа І-ІІІ ступенів № 10 Вінницької міської ради\"",
142+
> "scheme": "https://ns.openprocurement.org/ua/edrpou",
143+
> "uid": "21725150",
144+
> "uri": "http://sch10.edu.vn.ua/"
145+
> },
146+
> "address": {
147+
> "countryName": "Україна",
148+
> "postalCode": "21027",
149+
> "region": "м. Вінниця",
150+
> "locality": "м. Вінниця",
151+
> "streetAddress": "вул. Стахурського. 22"
152+
> }
153+
> }
154+
> }
155+
> }
156+
157+
< HTTP/1.1 201 Created
158+
< Content-Type: application/json; charset=UTF-8
159+
< Location: http://api-sandbox.openprocurement.org/api/0/tenders/8c2ba371505348ed8f5f0e5119a80451
160+
<
161+
{
162+
"data": {
163+
"id": "8c2ba371505348ed8f5f0e5119a80451",
164+
"tenderID": "UA-8c2ba371505348ed8f5f0e5119a80451",
165+
"modified": "2014-10-25T00:37:13.847358",
166+
"procuringEntity": {
167+
"id": {
168+
"scheme": "https:\/\/ns.openprocurement.org\/ua\/edrpou",
169+
"name": "\u0417\u0430\u043a\u043b\u0430\u0434 \"\u0417\u0430\u0433\u0430\u043b\u044c\u043d\u043e\u043e\u0441\u0432\u0456\u0442\u043d\u044f \u0448\u043a\u043e\u043b\u0430 \u0406-\u0406\u0406\u0406 \u0441\u0442\u0443\u043f\u0435\u043d\u0456\u0432 \u2116 10 \u0412\u0456\u043d\u043d\u0438\u0446\u044c\u043a\u043e\u0457 \u043c\u0456\u0441\u044c\u043a\u043e\u0457 \u0440\u0430\u0434\u0438\"",
170+
"uri": "http:\/\/sch10.edu.vn.ua\/",
171+
"uid": "21725150"
172+
},
173+
"address": {
174+
"postalCode": "21027",
175+
"countryName": "\u0423\u043a\u0440\u0430\u0457\u043d\u0430",
176+
"streetAddress": "\u0432\u0443\u043b. \u0421\u0442\u0430\u0445\u0443\u0440\u0441\u044c\u043a\u043e\u0433\u043e. 22",
177+
"region": "\u043c. \u0412\u0456\u043d\u043d\u0438\u0446\u044f",
178+
"locality": "\u043c. \u0412\u0456\u043d\u043d\u0438\u0446\u044f"
179+
}
180+
}
181+
}
182+
}
183+
184+
And again we have `201 Created` response code, `Location` header and body wth extra `id`, `tenderID`, and `modified` properties.
185+
186+
Let's check what tender registry contains::
187+
188+
curl -v http://api-sandbox.openprocurement.org/api/0/tenders/
189+
> GET /api/0/tenders/ HTTP/1.1
190+
> Host: api-sandbox.openprocurement.org
191+
>
192+
< HTTP/1.1 200 OK
193+
< Content-Type: application/json; charset=UTF-8
194+
<
195+
{
196+
"data": [
197+
{
198+
"id": "be40e257812044f3913534cc537d1f99",
199+
"modified": "2014-10-25T00:24:12.772078"
200+
},
201+
{
202+
"id": "8c2ba371505348ed8f5f0e5119a80451",
203+
"modified": "2014-10-25T00:37:13.847358"
204+
}
205+
]
206+
}
207+
208+
And indeed we have 2 tenders now.
209+
210+
Let's update tender by providing it with all other essential properties::
211+
212+
curl -v -H "Content-Type: application/json" -X PATCH --data @tender-update.json http://api-sandbox.openprocurement.org/api/0/tenders/8c2ba371505348ed8f5f0e5119a80451
213+
> PATCH /api/0/tenders/8c2ba371505348ed8f5f0e5119a80451 HTTP/1.1
214+
> Host: api-sandbox.openprocurement.org
215+
> Content-Type: application/json
216+
>
217+
> {
218+
> "data":{
219+
> "totalValue": {
220+
> "amount": 50000,
221+
> "currency": "UAH",
222+
> "valueAddedTaxIncluded": true
223+
> },
224+
> "itemsToBeProcured": [
225+
> {
226+
> "description": "Послуги шкільних їдалень",
227+
> "primaryClassification": {
228+
> "scheme": "CPV",
229+
> "id": "55523100-3",
230+
> "description": "Послуги з харчування у школах"
231+
> },
232+
> "additionalClassification": [
233+
> {
234+
> "scheme": "ДКПП",
235+
> "id": "55.51.10.300",
236+
> "description": "Послуги шкільних їдалень"
237+
> }
238+
> ],
239+
> "unitOfMeasure": "item",
240+
> "quantity": 5
241+
> }
242+
> ],
243+
> "clarificationPeriod": {
244+
> "endDate": "2015-05-29T00:00:00"
245+
> },
246+
> "tenderPeriod": {
247+
> "endDate": "2015-06-07T10:00:00"
248+
> },
249+
> "awardPeriod": {
250+
> "endDate": "2015-06-18T00:00:00"
251+
> }
252+
> }
253+
> }
254+
255+
< HTTP/1.1 200 OK
256+
< Content-Type: application/json; charset=UTF-8
257+
<
258+
{
259+
"data": {
260+
"clarificationPeriod": {
261+
"startDate": null,
262+
"endDate": "2015-05-29T00:00:00.000000"
263+
},
264+
"awardPeriod": {
265+
"startDate": null,
266+
"endDate": "2015-06-18T00:00:00.000000"
267+
},
268+
"tenderPeriod": {
269+
"startDate": null,
270+
"endDate": "2015-06-07T10:00:00.000000"
271+
},
272+
"modified": "2014-10-25T00:42:44.968106",
273+
"itemsToBeProcured": [
274+
{
275+
"unitOfMeasure": "item",
276+
"description": "\u041f\u043e\u0441\u043b\u0443\u0433\u0438 \u0448\u043a\u0456\u043b\u044c\u043d\u0438\u0445 \u0457\u0434\u0430\u043b\u0435\u043d\u044c",
277+
"valuePerUnit": null,
278+
"additionalClassification": [
279+
{
280+
"scheme": "\u0414\u041a\u041f\u041f",
281+
"id": "55.51.10.300",
282+
"uri": null,
283+
"description": "\u041f\u043e\u0441\u043b\u0443\u0433\u0438 \u0448\u043a\u0456\u043b\u044c\u043d\u0438\u0445 \u0457\u0434\u0430\u043b\u0435\u043d\u044c"
284+
}
285+
],
286+
"primaryClassification": {
287+
"scheme": "CPV",
288+
"id": "55523100-3",
289+
"uri": null,
290+
"description": "\u041f\u043e\u0441\u043b\u0443\u0433\u0438 \u0437 \u0445\u0430\u0440\u0447\u0443\u0432\u0430\u043d\u043d\u044f \u0443 \u0448\u043a\u043e\u043b\u0430\u0445"
291+
},
292+
"quantity": 5
293+
}
294+
],
295+
"tenderID": "UA-8c2ba371505348ed8f5f0e5119a80451",
296+
"totalValue": {
297+
"currency": "UAH",
298+
"amount": 50000,
299+
"valueAddedTaxIncluded": true
300+
},
301+
"id": "8c2ba371505348ed8f5f0e5119a80451",
302+
"procuringEntity": {
303+
"id": {
304+
"scheme": "https:\/\/ns.openprocurement.org\/ua\/edrpou",
305+
"name": "\u0417\u0430\u043a\u043b\u0430\u0434 \"\u0417\u0430\u0433\u0430\u043b\u044c\u043d\u043e\u043e\u0441\u0432\u0456\u0442\u043d\u044f \u0448\u043a\u043e\u043b\u0430 \u0406-\u0406\u0406\u0406 \u0441\u0442\u0443\u043f\u0435\u043d\u0456\u0432 \u2116 10 \u0412\u0456\u043d\u043d\u0438\u0446\u044c\u043a\u043e\u0457 \u043c\u0456\u0441\u044c\u043a\u043e\u0457 \u0440\u0430\u0434\u0438\"",
306+
"uri": "http:\/\/sch10.edu.vn.ua\/",
307+
"uid": "21725150"
308+
},
309+
"address": {
310+
"postalCode": "21027",
311+
"countryName": "\u0423\u043a\u0440\u0430\u0457\u043d\u0430",
312+
"streetAddress": "\u0432\u0443\u043b. \u0421\u0442\u0430\u0445\u0443\u0440\u0441\u044c\u043a\u043e\u0433\u043e. 22",
313+
"region": "\u043c. \u0412\u0456\u043d\u043d\u0438\u0446\u044f",
314+
"locality": "\u043c. \u0412\u0456\u043d\u043d\u0438\u0446\u044f"
315+
}
316+
}
317+
}
318+
}
319+
320+
We see the added properies merged with existing data of tender. Additionally the `modified` property updated to reflect the last modification datestamp.
321+
322+
Checking the listing again reflets the new modification date::
323+
324+
curl -v http://api-sandbox.openprocurement.org/api/0/tenders/
325+
> GET /api/0/tenders/ HTTP/1.1
326+
> Host: api-sandbox.openprocurement.org
327+
>
328+
< HTTP/1.1 200 OK
329+
< Content-Type: application/json; charset=UTF-8
330+
<
331+
{
332+
"data": [
333+
{
334+
"modified": "2014-10-25T00:42:44.968106",
335+
"id": "8c2ba371505348ed8f5f0e5119a80451"
336+
},
337+
{
338+
"id": "be40e257812044f3913534cc537d1f99",
339+
"modified": "2014-10-25T00:24:12.772078"
340+
}
341+
]
342+
}
343+

0 commit comments

Comments
 (0)