TIBCO Mashery® API Primer

Table of Contents

• Introduction
• Overview of the API Primer
• What You Will Learn
• An Introduction to APIs
• A Simple Example
• Breaking down the example
• Example of an API call
• Connecting to a Domain
• Summary
• Introduction to the Mashery Platform

Introduction

Overview of the API Primer

The purpose of this is to ensure that all users of the TIBCO Mashery^® platform have a firm understanding of the required technical background needed for more advanced Mashery use. 

What You Will Learn

This primer covers some of the common terminology and practices that are used when dealing with API Management. Some of this information is specific to Mashery and some may be more generic to the technologies used.

An Introduction to APIs

An Application Programming Interface (API) is a method in which data and services are exposed to developers through a defined and documented interface. When referring to API Management, we are specifically focusing on the governance of web services, a type of API that is accessible over a computer network via HTTP.

APIs are used in countless numbers of everyday scenarios, from checking train times to online banking, gaming and media. All of these systems can be explained as a process of making requests and responses. For example, a smartphone application may make a request to an airline for information about a particular flight. The airline will then serve a response to the application to display to the user. The format of this request and response is what defines an API.

API Management is the concept of exposing and controlling access to these services. As the number of developers who require access to a service increases, so does the need for control. The Mashery platform allows API owners to easily scale and manage their existing API program.

A Simple Example

Another common example of consuming APIs is simply browsing the web. When a user opens a web page, their browser connects to a server and requests the content of the page. The web server will respond with the HTML of the requested page and this is then rendered to the user by the browser. Using this example we can identify some of the common parties and actions of an API transaction:

The user (end-user or consumer) opens a webpage ?http://www.company.com/index.html?

The browser (user agent) makes a HTTP connection to ?http://www.company.com?

The browser (user agent) makes a GET request for ?/index.html?

The Web Server (origin server) accepts the connection and request and builds the response.

The content of index.html is sent to the browser.

The browser renders the content of index.html and displays it to the user.

In the above example the browser is acting as a User Agent, and is making an API request to the server and displaying the response to the end user.

Breaking down the example

We can break down the above example to identify some of the other common components of an API transaction. When the browser makes a connection to the web server, it uses a Universal Resource Locator (URL) to describe the request:

Here we can see highlighted the protocol (scheme), hostname and resource path. In a more complex example, we might see:

In this example the protocol is Secure HTTP (HTTPS), the resource path is for ?collection item? and we now have query parameters which includes the key/value pair ?ix = 0? in the request.

In addition to the URI, there are also hidden values sent to the web server as part of the request. These are not seen by the end user and are typically populated by the user agent (in this case, the browser). These are called HTTP Request Headers, and are sent as part of the request. These are always in the format ?Key: Value?. A common header is ?Accept? which tells the server what format the user agent would like the response. For example, when requesting a Cascading Style Sheet (CSS) file, a browser would include the header: ?Accept: text/css?. Headers can also contain information about the user agent, the end user, session information and language preferences.

Example of an API call

Web browsers make hundreds of different requests in order to render a web page, however API calls are usually much more granular or precise. Here we will look at a more typical API call:

In this simple API call, we are also including an ?API key? in our request which will be used by the service provider to determine who is calling the API.

Connecting to a Domain

In the above example ?api.company.com? is the hostname of the URL. This is a label for a Domain Name Service to resolve to an address, usually an IP address or the hostname of another service.

Summary

Having a good grasp of the elements of an API call is key for understanding the Mashery Platform. Protocol, hostname, path, query parameters and request headers are basic components of an API call.

Introduction to the Mashery Platform

The Mashery Platform routes traffic between end users and an existing API service. The end user makes a connection to the Mashery Traffic Manager, the Traffic Manager will inspect the request and then make a subsequent request to the appropriate service.

Each request that is received by the Mashery Platform is identified by the hostname and path. This forms a unique combination that is associated with a single Mashery Endpoint. The Endpoint defines how the connection should be handled.

For example, when a connection is made to api.example.com/collection/item, this will resolve through DNS to example.api.mashery.com. The Mashery Traffic Manager will use the combination of ?api.example.com? and ?collection/item? to identify which endpoint is being called.

Information about how the endpoints are configured and managed are covered in Mashery Training as part of the implementation project.