Beginner’s Guide to REST API and GRAPH API

Mapping the Cybersecurity Landscape
8th January 2019
OTP
One-time Passwords (OTP): A Beginner’s Guide 2023
9th January 2019
Show all

Beginner’s Guide to REST API and GRAPH API

API white bg
 

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 and for that you can use any of the API management tools listed here.

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

 
10th May 2023

5 Reasons Why Web Applications Need a Software Licensing Engine

Dedicated licensing engine provides significant value and helps overcome complexity. In this blog we explain the complexity and how to solve it.
7th October 2022

How Centralized Software License Management Will Increase Your Revenue

License management is typically looked at simply as a cost of doing business. When done correctly, license management can be an engine of revenue growth, removing […]
18th August 2022

Cloud-based Software Licensing | The Modern Way

Every kid coming out of Harvard, every kid coming out of school now thinks he can be the next Mark Zuckerberg, and with these new technologies […]
11th April 2022

Software Licensing System – The Build vs. Buy Conundrum

To build or buy a licensing system – the huge question all growing software vendors will face. This blog will help you make an informed decision.
13th December 2021

Licensing As a Service – Why It’s the Modern Way of Software Licensing

Licensing as a Service, a new method of software licensing, offers flexible and effective means of monetizing software products quickly and easily.
20th August 2021

10Duke 101 – Understanding the Basics of 10Duke Licensing

A brief introduction to 10Duke’s Licensing Solution. We will go through its main concepts and how to integrate with 10Duke, including delegation of authentication, product configuration […]
12th May 2021

Software Activation – The Good, The Bad and the Modern

Software Activation is a technology that verifies a software product has been legitimately licensed for use. Learn how to do it effectively.
29th March 2021

Is Sharing Really Caring? Not If It’s Your Password

Password sharing may seem harmless, but it actually puts your business, employees and customers at risk. Find out why what you can do to prevent it.
18th February 2021

Software IP Protection – How to Protect Software Intellectual Property?

Software IP protection strategy is not just about limiting access. The best IP protection software also aims to enhance customer experience.

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.