What is an API?

November 27, 2019 by Haley Elmendorf

What is an API by Advicent

about the author:

Haley Elmendorf

Associate software developer

Haley Elmendorf is an associate software developer at Advicent, the financial planning technology provider of choice for nearly 100,000 financial professionals.

It seems like all the rage is around APIs these days. The flexibility! The value-add! Digital strategy!

If you find yourself asking "but what is an API?" you are certainly not in the minority. In this article, I will explain the basics of APIs and the terminology around them.

API overview

At its most basic, an API allows for two applications to talk to each other. API stands for Application Programming Interface. It is the "plug in" point for one application to access data from another application. It establishes a “contract” of communication which dictates what input information it requires in order to produce certain output information or actions. It communicates this information through a series of endpoints.

You can think of a website as made of multiple layers. Two such layers are the data layer which contains the data it needs to display, and the visual layer which does the displaying. For websites built with an underlying API layer, the webpage accesses and serves up the data by calling to the API, which is the broker between the webpage and the source of the data (e.g. database). An API is like a waiter/waitress at a restaurant. You tell them what you would like to eat, they deliver that message to the cook, and then bring the food back to you.

If the waiter/waitress is the API, then the API “consumers” are the patrons of the restaurant. The menu presented to each patron is the same; I could request the same dish as someone at another table and the API/waiter/waitress would deliver the same meal to each of us. We could then use it for whatever we please - eat it, box it up and take it home, throw it on the floor, etc.

You have likely seen APIs being used all over the internet nowadays for a variety of reasons. When you think of websites that offer you the opportunity to "like" or share their page on Facebook, that website is accessing your Facebook data through an API. The same goes for shopping sites that offer to let you pay through PayPal or show embedded YouTube videos. They are all using APIs!

APIs are attractive and popular because they offer developers the opportunity to utilize the data from an application outside of that application. NaviPlan partners are also given the power and flexibility of API access which enables the secure retrieval of NaviPlan data for use and display in their own custom-built websites and applications.

How APIs work

An API is accessed by making a request. A request is made up of a method, headers, and a body, sent to an endpoint. Let's look at an example from NaviPlan's Planning API, as seen in NaviPlan's developer documentation:



The endpoint is comprised of the URL you request and the method you use to request it. If you were to access this endpoint, you would enter "/api/v1/plans/{planId}/accounts/{id}" after the root URL, which would be given to you as an API consumer.

The method here is GET. The HTTP protocol has the following methods:

  • POST 
  • GET
  • PUT
  • PATCH
  • DELETE

We will not get into these in detail here, other than to say accessing a GET method will give you data back in return.

Let’s say we have a client with a plan id of 1234 in NaviPlan and an account id of 5567. If we made a request to the GET endpoint, it would look like this:

rootURL/api/v1/plans/1234/accounts/5567

The response we get back then might then look something like this (note: this response has been simplified for sake of example):


{
  "apiVersion": "v1",
  "data": {
    "id": 5567,
    "marketValue": 156233,
    "numHoldings": 1,
    "numSavingsStrategies": 1,
    "investmentType": "InvestmentPortfolio",
    "description": "InvestmentSavings",
    "owner": {
      "memberId": 6589,
      "memberType": "Client"
    }
  }
}

A developer could use this formatted request/response pattern to display requested data how they would like it - for NaviPlan partners, that would most likely mean inside of a partner's already-existing website or client portal.

Now for a review on terminology. An API is a generic term that is generally used in reference to an intermediary application that communicates through a collection of endpoints that together form a cohesive product. Those endpoints are further grouped into controllers. Several endpoints comprise a controller, and several controllers comprise the communication layer of an API. Looking at Advicent's Planning API again for an example, we see that some of the controllers included are Accounts, Expenses, and Households. Within the Accounts controller, there are many endpoints that allow the user to create, retrieve, update, and delete those accounts. All this functionality together is an API. 

While this is just scratching the surface of the breadth of APIs and what they can do, you now know the basic concept of what an API is and what they can offer.

To learn about the new NaviPlan APIs that enable firms to build fully customized self-directed planning experiences, click here.

Sign up for the
Advicent newsletter