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

Made with Slides.com