Beginner’s guide to REST API and GRAPH API

Software Licensing in the Cloud: Achieving Competitive Advantage
Software Licensing in the Cloud: Achieving Competitive Advantage
8th January 2019
one-time-password
One-time passwords: A beginner’s guide
9th January 2019
Show all

Beginner’s guide to REST API and GRAPH API

We are all connected to each other in a way that we have never been connected before. You can buy socks, share an image with thousands of people, make a dinner reservation and book a ticket to Mexico in less than 10 minutes with just a few clicks of a button. To make this possible data needs to move seamlessly between different applications. But how? How is it possible for lots of different applications and resources to communicate? How it is all connected? The unsung hero of our connected world is the Application Programming Interface (API). APIs make it possible for interactions between applications, data and devices to take place. They are the behind the scenes, uncelebrated superstars accountable for connecting isolated products and functions into the rich tapestry of our interconnected world.

What is an API?

An API is just a clearly defined set of functions and procedures that allows access to the features or data of an operating system, application, or other resources. There are APIs in your computer, smartphone, operating system and even in some refrigerators and their function is to enable systems to communicate.

A commonly used analogy is to think of an API like a waiter in a restaurant. The waiter passes requests from the customers to the kitchen and also delivers information and responses back. APIs simply enable communication between third-party software applications and shared resources or endpoints.

The most common types of API are web APIs, which you interact with using HTTP and typically the following HTTP methods are used.

From the HTTP methods listed above, you can successfully interact with almost any endpoint.

✅ GET, HEAD, OPTIONS and TRACE methods are used to retrieve data from an API server.

✅ PUT, POST and PATCH requests are used to create or modify a resource.

✅ DELETE is exactly as it sounds and enables you to delete the resource at the specified URL.

✅ OPTIONS returns data describing what other methods and operations a server supports.

✅ CONNECT starts a two-way communication with the requested resource, in effect opening a tunnel.

 

As a software developer, good APIs make it easier to develop computer programmes by providing essential building blocks. This means that you don’t have to build (and maintain) all of the code for every function of an application yourself. You just need to learn how to talk to the APIs that are available. For example, say you build an app that sells concert tickets and you want to add a function that displays venue locations. You do not need to map out whole cities and countries yourself (even if you had the resources to do so), you can simply integrate the Google Maps API into your application.

By using standard HTTP methods, communication is greatly simplified. The APIs only expose the objects or actions that developers need in order to successfully interact with a resource and API documentation is usually provided to facilitate usage and reimplementation. Uniform Resource Locators, or URLs, is an identification system for the location of resources on the Internet. URLs are powerful, as they allow APIs to be referenced across any accessible server.

What is REST?

As web users progress through a network of web resources each action (such a clicking on a link), causes a change of state. For example, the homepage of a website is one state and when you click on a link you transition to a different state, resulting in the next resource or set of resources, being transferred to you for use.

REpresentational State Transfer (REST) is an architectural style that defines a specific set of constraints and properties ensuring that its possible for computer systems or software to exchange information.  REST is what makes it possible for you to easily and continually change state as you navigate through web resources.

A RESTful API is simply an API that follows the rules of REST specification. REST rules dictate how software components will talk, what kind of message they will send to each other and how requests and responses will be handled. It is an agreed way of doing things.

Consider these two examples;

DELETE API/users:userID HTTP/1.1

GET API/users/delete:userID HTTP/1.1

The second example is illogical, a get method is being used to carry out a delete request and it is therefore considered non-RESTful. The rules of REST ensure that you are able to easily fetch information from a resource location.

REST APIs are stateless, meaning that each call for data contains all of the data necessary to complete a call successfully and calls for data are made independently of one another. Using a stateless protocol and standard operations has huge advantages in that REST systems can provide fast performance, reliability and scalability. However, there are also some drawbacks, which fall loosely into two categories; data over-fetching and data under-fetching.

You can make a request from a resource every 10 seconds if you want to and the remote server will (probably) always answer, presuming it hasn’t collapsed due to server overload. However this is inefficient, so instead you can apply the Hollywood principle (‘don’t call us we’ll call you’). Instead of calling for data every 10s to find out if any information has changed, you can apply a webhook so that the API will call you when it has new information.

This can help solve the problem of data over-fetching, but what happens if you want to call information about several objects at the same time? To attempt to solve this issue, a new design has gained ground over the last few years – Graph APIs.

 

What is a GRAPH API

If you’ve consumed a web API in the last decade, there is a good chance it was a REST API. The data was likely organised around resources, HTTP methods (or verbs) were used and responses will have included the object ID. RESTful API design has been the dominant standard in the industry for a while, however, REST has its problems. Clients can easily get stuck in a pattern of data over-fetching, particularly where APIs are poorly implemented. They will, for example, fetch an entire resource just to get one or two pieces of information and fetch the object too frequently. On the other hand, a client may regularly need to fetch several objects at the same time, but can’t fetch all the information in the same request, (data under-fetching).

In mathematics, a graph is a concept describing nodes and their connections and this is where the GRAPH API gets its name. The Graph API isn’t a completely new type of API, all of the information is still available under a single RESTful endpoint. However, Graph APIs allow you to traverse relationships within data using nodes and their connections. A GRAPH API is typically composed of;

  • ✅ nodes — basically individual objects, such as a User, an image, a Page, or a Comment
  • ✅ edges — connections between a collection of objects and a single object, such as multiple comments on a single image
  • ✅ fields — data about an object, such as a User’s name or date of birth

To get information about a node you directly query its ID. If you want to get specific data (called fields) about a node, you can include the fields parameter and specify which fields you want to be returned in the response. Most nodes have edges, which can return collections of objects connected to that node. To query an edge, you use both the node ID and the edge name.

GRAPH APIs are a very controlled way to query massive volumes of data in an efficient way, shortening the response time, which in turn means data can be delivered in real time and more intelligently than when using REST APIs.

Facebook launched on 4th February 2004 and as of the second quarter of 2018, Facebook had 2.23 billion monthly active users worldwide. Aside from personal data, Facebook holds huge databases of information relating to every user including their timeline, posts, pages, comments, events, connections, interests and much more.

Consider a post to your Facebook timeline that has comments attached to it. Using a REST API the client would need to make separate HTTP requests to fetch the post, photo, comments, details of the author of each comment etc., which quickly becomes a large number of HTTP calls. Version 1.0 of the Facebook Graph API launched on April 21, 2010, in order to help optimise data fetching.  Using a GRAPH API the required details can easily be fetched in a single query using fields to fetch the top level data such as the post, photo or page, and at the same time return a query of the nodes and edges of a post or image – such as the comments attached to it as well as the authors of those comments.

By using nodes and their connections, you can build dynamic queries that are only related to the data that you actually need, instead of fetching all of the data all of the time. You can also create so-called differential queries, which allow you to request only the changes that have happened on the result set of a query since the previous query was run. In this way, Graph APIs provide superior performance for querying any related data, whether in large volumes or small.

10Duke

10Duke offers a number of authentication and licensing solutions delivered as REST and GRAPH APIs.  Developer Guides for 10Duke APIs are available on our developer website, plus a free to test demo service that will allow you to evaluate each API.

Share:
Request a Demo