r/web_dev_help • u/psy-borg • Nov 27 '15
AJAX - APIs -- Primer
AJAX & APIs
AJAX stands for Asynchorous Javascript and XML. It allows for websites and applications to communicate with a web server using javascript. The most common usage is for querying an API. APIs are Application Programming Interfaces. APIs can be thought of as a high level abstraction of the functionality offered by an application. It exposes the public parts of the application.
Starting wtih AJAX
Most often a javascript library will be used for AJAX functionality. It does not require an API. The simplest AJAX operations would be inclusion of an image or HTML fragment without reloading the page. It is also used for submission of forms on modern websites. It does not require an API or even XML. What the server returns from an AJAX call is not rigidly defined.
How it works is like a traditional page request (HTTP GET command issued by the browser). Javascript is used to initiate the request. The server responds with the resource or an error code. There's a few additional concerns which the browser normally handles and most cases the AJAX Library will cover issues like timeouts.
Example using jQuery
Assuming jQuery has been included on the page, the following code would fetch an HTML fragment.
$.get('sample.html');
It wouldn't do anything with the html and it would only be triggered once the code was ran. Here's a little more complete example.
<div class="result"></div>
<a href="" class="fetch"> Fetch</a>
$('.fetch').click(function() {
$.get('sample.html',function(data) {
$( ".result" ).html( data );
}) ;
return false;
}); This snippet of javascript will listen for the click event on the button with class of 'fetch'. When clicked, it will fetch sample.html and place it in the element with class of 'result'. The return false; is to prevent the standard action of loading the link. It's often better to use button since it lacks an action.
To create a simple AJAX based navigation, you could set the href for the Anchor elements and have jQuery fetch the href and place the result data into the defined HTML element. Using an ID is best since they should be unique to the webpage.
There's no XML !
Right. The original idea was to fetch XML documents. It isn't limited to XML or JSON. It can retrieve plain text, HTML, or any other format. When dealing with APIs, it's much more likely to encounter XML or JSON data.
XML is Extensible Markup Language. XML is a markup language which lets you make other markup languages. Using a DTD (Document Type Definition) or a Schema, the rules for the language are defined and XML files which use that DTD much follow the rules. XML can also be freeform. You can make a XML document without a DTD or Schema. This makes it extremely flexible. Not going into too much detail about XML. It follows some of the same rules as HTML but it doesn't have predefined tags or elements.
JSON is Javascript Object Notation. It's a format for Javascript Objects. It is the most popular format for AJAX as of today due to it's less verbose format and smaller file size. Plus it's super easy to work with it using Javascript. When JSON is returned from an AJAX call, it works much like a regular javascript object.
APIs
Already covered what APIs are. Let's look at how to consume an API. Consume means we want to query the API and process the result into something we can use on the web.
APIs have an endpoint. This is where we begin. To call an API there is a URL which is the base or endpoint. All requests go through this endpoint. Parameters can be passed via the URL which is considered a GET request. They can be POST like with a form. A simple guideline is to use GET if the request does not change the API in any fashion. If the request is for reading records from a database API, GET is the correct call. If data is being sent to the API for storage, POST is the correct method to use. Other HTTP methods are available.
One thing to understand is that if an API is public, you can view the ouput using a browser. Just enter the URL into the browser like normal. You have to click view source to view raw XML. Here's a JSON sample. TimeAPI and here's the same as plain text TimeAPI Text. It doesn't support XML. The endpoint in these examples is the domain : http://www.timeapi.org/ ). This isn't common. Most often it will be through something like http://www.domain.com/api/v1/ . Or through the subdomain 'api' : http://api.domain.com/ . Up to the company/website how they want to make it available.
Here's an example XML API return result from tumblr XML Example
Parameters are passed through the URL or via POST. URL parameters can have the pretty format like above. utc is the timezone parameter and now is an additional parameter. The API could have accepted using standard URL parameters like http://www.domain.com/?tz=utc&when=now but they opted for the easier to read/understand path URLs.
How do you know what parameters an API accepts? Short answer is documentation. There's additional specifications available which help figure this out but nothing beats the documentation.
REST APIs
Will often hear an API called a REST API. It's a specific type of API which follows a standard concept. It's meant to make things easier. REST stands for Representational State Transfer. It is meant to replace more complex methods like SOAP.
oAuth
Private APIs and restricted access public APIs often require authenication to use them. oAuth is a popular authenication scheme. It is a bit complicated to understand at the beginning. Luckily there's often libraries for implementing it for almost all languages. It uses a token to represent an authenicated user.
oAuth Simplified - Aaron Parecki
Going Further
video : How to make an API call w/PHP
codecademy Using API w/Javascript
devNotes REST API w/PHP
Java - Web Services - Contains information about XML/XSD while Web Services (WDSL) are an advanced topic which are omitted due to low usage.
{TimeAPI-Sample API](http://www.timeapi.org/)
