API's & Ajax

use the arrow keys to navigate; press space for slide overview

API's & Ajax

Client–server model

HTTP Client–Server model

  • In order to use API's and AJAX, it is very important to understand how the HTTP client–server model works. Some definitions:
    • a resource is an HTML page, CSS file, JS script, image, font...
    • a client is the software requesting a resource: browser, app, program...
    • a server is the software/hardware hosting and delivering resources to clients
    • a request is a message from client to server
    • a response is a message back from the server to the client

HTTP Client–Server model

  • A request/response has three steps:
    • step 1: the client sends a request to the server
    • step 2: the server processes the request
    • step 3: the server returns a response to the client
http
source: www.ntu.edu.sg

Step 1: HTTP request (1)

  • An HTTP request message has the following parts:
    • request line: contains URL, method and HTTP version
    • request headers: contains extra info like browser/OS version, expected response type...
    • request body: contains data attached to the request
  • Example of a HTTP GET request to retrieve an image:
http

Step 1: HTTP request (2)

  • The request method defines which action is required from the server. Many methods exist (overview), but the only two important are:
    • GET: retrieve data
    • POST: send data (e.g. form data, uploaded file...)
  • The main difference between GET and POST is that a POST request body can contain data. Example of a POST request with login data sent to a PHP server script login.php:
http

Step 1: HTTP request (3)

  • Example of a POST request to upload a file to a ASP.NET server script upload.aspx:
http

Step 2: Processing the request

  • When the server receives the request, a lot of magic happens: locating resources, checking permissions, executing scripts... This lies outside the scope of this course, so we'll just consider the server a black box:
http

Step 3: HTTP response

  • The HTTP response message is similar to the HTTP request:
    • response line: contains HTTP version and status code (e.g. 200=ok, 403=forbidden, 404=not found...)
    • response headers: contains extra info like compression type, content type...
    • response body: contains the requested resource (e.g. image, HTML code...)
http

Initiating a HTTP request

  • HTTP requests can be initiated in many ways.
  • If you just want to retrieve an URL content, you can
    • enter a URL in the address bar (browser)
    • click a link in a page, email, PDF...
  • If you want to test a HTTP request with control over custom headers, body content, method..., you can build and send a request
  • Finally, you can also send requests from scripts:
    • from a .NET application with the System.NET.WebRequest class
    • from a PHP server script with the cUrl module
    • from Javascript with the fetch() method → this will be the focus of this presentation

Inspecting request/response (1)

  • In the browser you can inspect request/responses on the Network tab of Chrome devtools. Example when requesting the Toledo portal page:
http

Inspecting request/response (2)

http
  • Note that this request generates a waterfall of other requests:
    • first the main URL is loaded, portal/; the response will return the HTML of the page
    • then all resources linked in the HTML (images, CSS, scripts...) are loaded in the order in which they appear
    • then all resources linked to these resources are loaded (e.g. images in CSS, audi in scripts...)
    • ...

Inspecting request/response (3)

http
  • Click on a request to inspect:
    • request URL, status code
    • request and response headers
    • response body
    • ...
  • Response status codes:
    • 200 - get ok
    • 201 - create ok
    • 301 - permanently moved
    • 400 - bad request (missing parameters)
    • 401 - not authorized (e.g. API key not given)
    • 404 - requested data not found
    • 405 - method not allowed (e.g. wrong verb)
    • 500 - internal server error

Inspecting request/response (4)

http
  • Example showing the response for a CSS file request

Inspecting request/response (5)

http

API's & Ajax

API's

What is an API

  • An API (Application Programming Interface) is a software service that offers a set of functions that other applications can consume remotely:
    • reading & searching data
    • weather service
    • updating content
    • authentication
    • complex calculations
    • image compression/conversion
    • ...

What is a Web API

  • In a web context it is called a web API. It follows the client–server model:
    • the web application sends a request to the API, optionally with request data
    • the API function sends back a response, optionally with readable response data
  • Benefits from consuming a web API:
  • Benefits from offering a web API:
    • make your products information available for price aggregators
    • split your huge application in smaller independent components
    • see how people build cool stuff with your data

Finding Web API's (1)

  • Almost all large web applications like Youtube, Google Maps, Dropbox, Twitter, Flickr etc. have web API's that you can use as a developer.
  • Just Google the API, e.g. search for "Flickr API", and you'll find the docs:
http

Finding Web API's (2)

  • Smaller dedicated API's also exist, e.g. weather service, dog pictures, funny quotes... Finding them may be a little harder; rapidapi.com has a nice collection:
http

Using Web API's (1)

  • How you can use a web API varies greatly, from very simple to very difficult. You will have to study the documentation. Things to consider:
    • authentication:
      • some API's are completely open (no effort)
      • some require you to apply for an API key that you have to include with every request (easy)
      • some require complex authentication methods like OAuth (too difficult for this course)
    • price/quota:
      • a few API's are still free and unlimited (but less and less)
      • most API's are free but have daily quota linked to the API key
      • in all other cases, you'll have to open your wallet
    • request:
      • make sure the REST (URL-based) request format is supported, beware of older formats like SOAP or XML-RPC
      • for the name of the functions and parameters, check the documentation
      • some API's require you to include extra headers with the request (e.g. API key)
    • response:
      • the response may have any format (XML, HTML, plain text...), but the most common and easiest is JSON (JavaScript Object Notation, see further); make sure it is supported

Using Web API's (2)

  • To summarize, if you pick a web API, make sure:
    • the API is open or requires a simple API key which you can get by easy registration
    • the API is free or has sufficient free daily quota
    • the REST request format is supported
    • the JSON response format is supported
    • it is well-documented and easy to use

Open API example

http

API key example (1)

http

API key example (2)

  • You can do the same request with Postman:
http

About JSON (1)

  • JSON (Javascript Object Notation) is a string representation of a single Javascript object holding all information.
  • An example JSON string is {"course":"RIA","lecturers":[{"id":1,"name":"Davy De Winne"},{"id": 2,"name": "Bramus Van Damme"}]}, or in a more readable layout (use this beautifier):
    {
      "course": "RIA",
      "lecturers": [
        {
          "id": 1,
          "name": "Davy De Winne"
        },
        {
          "id": 2,
          "name": "Bramus Van Damme"
        }
      ]
    }

About JSON (2)

  • JSON is basically a keys-values tree, where
    • keys are string (double quotes required!)
    • values are string, number, Object, Array, boolean or null
  • Well supported in most programming languages (PHP, .NET, Javascript...)
  • JSON FTW!
    • easy to work with (clientside and serverside)
    • less overhead than other response formats like XML
    • supported by all modern web API's

API's & Ajax

AJAX with fetch()

About AJAX

  • Now our final question: how can we use web API's in Javascript?
  • The technique to make a request to a server from Javascript is called AJAX:
    • Asynchronous Javascript and XML
    • allows loading extra resources and data without leaving the page
    • originally created by developers of Outlook Web Access (Microsoft) back in 2000, later picked up by Google in Google suggest
  • There are various ways to implement an AJAX call:
    • oldest: with the XMLHttpRequest object
    • newer: with specialized libraries, e.g. jQuery
    • newest: with the new Javascript fetch() method, now widely supported

XMLHttpRequest syntax

  • The XMLHttpRequest syntax (check your console):
    let xhr = new XMLHttpRequest();
    xhr.addEventListener('readystatechange', function() {
      if (this.readyState == 4 && this.status == 200) {
        console.log('data received: ', this.responseText);
      }
    });
    xhr.open('GET', 'https://dog.ceo/api/breed/hound/images/random', false);
    xhr.send();
  • hard to use; I wouldn't recommend this syntax

JQUERY syntax

  • The jQuery syntax (check your console):
    jQuery.ajax({
      url: 'https://dog.ceo/api/breed/hound/images/random',
      method: 'GET',
      success: function(result) {
        console.log('data received: ', result);
      },
      error: function(err) {
        alert('request failed: ', err);
      }
    });
  • requires an external library (jQuery)
  • is easier to use, but I wouldn't recommend using this syntax either

fetch() syntax (1)

  • The fetch() syntax (check your console):
    let url = 'https://dog.ceo/api/breed/hound/images/random';
    fetch(url)
      // handle response
      .then(function(resp) {
          console.log('response status: ', resp.status);
          return resp.json();
      })
      // handle response data
      .then(function handleSuccess(data) {
          console.log('data received: ', data);
      })
      // catch errors
      .catch(function(err) {
          console.log('request failed: ', err)
      });
  • this is the way to go!

fetch() syntax (2)

  • If you prefer, you can use named functions instead of anonymous:
    let url = 'https://dog.ceo/api/breed/hound/images/random';
    function handleResponse(resp) {
      console.log('response status: ', resp.status);
      return resp.json();
    }
    function handleSuccess(data) {
      console.log('data received: ', data);
    }
    function handleError(err) {
      console.log('request failed: ', err)
    }
    fetch(url)
      .then(handleResponse)
      .then(handleSuccess)
      .catch(handleError);
  • this is the way to go!

fetch() custom headers

  • Example from the Chuck Norris API, an API that requires custom headers:
    let url = 'https://matchilling-chuck-norris-jokes-v1.p.rapidapi.com/jokes/random';
    let options = {
      headers: {
        'X-RapidAPI-Host': 'matchilling-chuck-norris-jokes-v1.p.rapidapi.com',
        'X-RapidAPI-Key': 'FLd7sJMCXBmshkCvZXkHKWBWSYt6p1lHgIZjsnuLCh9gVyZf1I'
      }
    };
    fetch(url, options)
      // handle response
      .then(function(resp) {
          console.log('response status: ', resp.status);
          return resp.json();
      })
      // handle response data
      .then(function handleSuccess(data) {
          alert(data.value);
      })
      // catch errors
      .catch(function(err) {
          console.log('request failed: ', err)
      });

AJAX Flickr demo (1)

  • Let's build a small application using the Flickr API. The HTML and CSS:
    <!DOCTYPE html>
    <head>
      <title>Ajax example</title>
      <meta charset="utf-8">
      <style>
        #pics {
          display: flex
          flex-flow: row wrap;
        }
        #pics img {
          height: 200px;
          display: block;
          margin-top: 20px;
          margin-right: 20px;
        }
      </style>
    </head>
    <body>
      <input id="search" type="text" placeholder="search here" />
      <div id="pics"></div>
    </body>
    </html>

AJAX Flickr demo (2)

  • The Javascript fragment for making our API call:
    // base URL
    let base = "https://api.flickr.com/services/rest/?";
    
    // append parameters
    let params = new URLSearchParams();
    params.append('method', 'flickr.photos.search');
    params.append('extras', 'url_m');
    params.append('per_page', 20);
    params.append('format', 'json');
    params.append('nojsoncallback', 1);
    params.append('api_key', '6ecfcd8d4a3b8a04da6093733db989a2');
    params.append('text', searchval);
    let url = base + params.toString();
    
    // AJAX call
    fetch(url)
      .then(onResponse) // TODO: implement onResponse
      .then(onSuccess) // TODO: implement onSuccess
      .catch(function(err) {
          console.log('Request failed', err)
      });

AJAX Flickr demo (3)

  • The complete script:
    window.addEventListener('load', function() {
      // DOM
      let pics = document.getElementById('pics');
      let search = document.getElementById('search');
    
      // search field event
      search.addEventListener('keypress', function(e) {
        if (e.which == 13) {
          pics.innerHTML = '';
          makeSearch(this.value);
        }
      });
    
      // handle fetch response
      function onResponse(res) {
        // error
        if (res.status < 200 || res.status >= 300) {
          console.log('error with status ' + res.status);
        } else {
          console.log('response ok ' + res.status);
          return res.json();
        }
      }
    
      // handle fetch data
      function onSuccess(data) {
        // all ok
        for (let i = 0; i < data.photos.photo.length; i++) {
          let img = document.createElement('img');
          if (data.photos.photo[i].url_m) img.setAttribute('src', data.photos.photo[i].url_m);
          pics.appendChild(img);
        }
      }
    
      // make the search
      function makeSearch(searchval) {
        // base URL
        let base = "https://api.flickr.com/services/rest/?";
    
        // append parameters
        let params = new URLSearchParams();
        params.append('method', 'flickr.photos.search');
        params.append('extras', 'url_m');
        params.append('per_page', 20);
        params.append('format', 'json');
        params.append('nojsoncallback', 1);
        params.append('api_key', '6ecfcd8d4a3b8a04da6093733db989a2');
        params.append('text', searchval);
        let url = base + params.toString();
    
        // AJAX call
        fetch(url)
          .then(onResponse)
          .then(onSuccess)
          .catch(function(err) {
              console.log('Request failed', err)
          });
        }
      }
    });
    

Things to consider

  • AJAX is essential in modern web development:
    • no reloads
    • faster
    • less bandwith used
  • But beware:
    • no browser history, back button is broken, no bookmarking
    • search engines do not always index injected content
Odisee logo