API 101
Using the WEB API
Today
- Some REST/HTTP background info
- Reading
- Saving
- Api features
- Field filtering
- Filtering in the api
HTTP
- Hypertext Transfer Protocol (HTTP)
- Application layer protocol
- HTTP -> TCP -> IP
HTTP Methods
- GET (Get..)
- POST (Create)
- PUT (Update)
- DELETE (Delete..)
- PATCH (Partial update)
- … OPTIONS, HEAD …
Also referred to as “verbs” for web language
HTTP Status codes
-
1xx - Informational (100-continue ; 102-processing)
-
2xx - Success (200-OK; 201-Created; 204-NC)
-
3xx - Redirection (301-Moved; 302-Found;...)
-
4xx - Client Error (400-bad request; 401-unauthorized..)
- 5xx - Server Error (500-internal server error;...)
404 - Not found
HTTP Request
https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#/media/File:Http_request_telnet_ubuntu.png
Content Negotiation
-
The process by which the client determines the representation of the resource
-
Can be done through HTTP header
- Accept: application/json
-
Can be done through URL extension (DHIS2)
-
http://localhost:8080/restService/person.json
-
Takes precedence over accept ...
-
REST
-
Representational State Transfer
-
REST is an architectural style, a way to design web-services (WS) or web-api
- Other architectural styles like
- XML-RPC
- SOAP
REST
-
Resources - sources of information
- Are identified using URI
- Generally a resource represents a multiple/single entity of the same type
-
Complex when your data is a graph (linked entities)
-
Rebuilding graph on client by doing multiple requests
-
Practical stuff
- Getting set up
- Authentication
- Doing some api work
Browser addon or cURL
goo.gl/G2VjZc
goo.gl/LRnKLb
Chrome
Firefox
cURL
- `-v` for more information
- `-u` for adding Basic auth
curl https://apps.dhis2.org/demo/api/dataSets.json -u admin:district -v
curl -H "Content-Type: application/json" -X PATCH -d '{"code":"IN_394130"}' \
http://localhost:8080/dhis/api/indicators/tcs5YGnjiKo.json -u admin:district -v
curl -H "Content-Type: application/json" -X PATCH -d @data.json \
http://localhost:8080/dhis/api/indicators/tcs5YGnjiKo.json -u admin:district -v
Local or Demo
https://apps.dhis2.org/demo/api
Authentication
- Basic Authentication
- base64(admin:district)
- Do not use without SSL
- OAuth 2
- More advanced (See docs)
JSON Data
goo.gl/y5qGfW
Lets go! :)
Copy of DHIS2 API 101
By markpolak
Copy of DHIS2 API 101
- 801