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;...)

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! :)