How can I use a rest API?

So you found that your SaaS app has API documentation, and now you wonder what you can do with it? In this article we clear up what APIs are, and show you useful next steps to use them to your advantage.

Simple API explanation

More precisely, this is just a quick summary of what a RESTful API is, as nearly 100% of all APIs are of this variant. So let's define both acronyms. The important one is API which is short for Application Programming Interface, this is an architecture that allows data to be exchanged between applications. Then there is REST (which means the API is RESTful); this describes the standardized principle through which this exchange occurs.

As a comparison, imagine API stood for a cable, that could mean literally any cable. In this example, REST would be the same as the USB standard, being universally agreed to follow certain principles.

What is the API documentation for?

API documentation is like an index of all the endpoints available within an API and instructions on how to call them. Endpoints are like different extensions in a phone system and you can call different endpoints within the same parent API.

For example, a CRM application might have different endpoints for calling contacts, deals, conversations, campaign tracking. These will all have different attributes they send you back, but there will be some patterns shared across all endpoints. For example, if an API allows you to get paginated responses than this should apply across all endpoints regardless of their specific nature.

Is API the same as middleware?

They're similar. While middleware allows you to package on-premises data sources (like databases) into an API, nearly every SaaS business app already comes with an API so there is no need to use any middleware. Basically, this means middleware is just a "bridge" that you use when you need to connect on-premise servers and legacy data to an internet-bound application or service.

Is RPA the same as an API?

API and RPA have similar goals, but they differ in a few key points. Robotic Process Automation describes little utility "bots" that can follow step-by-step recipes that they were pre-programmed with. For example, they can wait for a trigger, then open a record, update a value and save it.

Popular examples would be Zapier or Microsoft PowerAutomate.

APIs can be used at any point in such RPA "recipes", so either as a trigger, as a step along the way or even the results could be available via an API. Where RPA goes above APIs is that certain RPA approaches can even access and manipulate data not available via API. RPA does this by opening websites or apps in a virtualized machine and clicking a pre-programmed sequence of buttons in order to scrape data in a structured way.

Examples of providers for these types of RPA would be Automation Anywhere or UiPath.

Use cases RPA can typically do, that APIs can't

• Logging into a user's 401k pension account to obtain their payments history, current balance, etc.

• Extracting a specific list of leads from a CRM so that it can be filtered in ways the UI of the application isn't supporting

• Get a list of workflow tasks from a legacy web application where there is no easy way to obtain such a list with a database connector

• Do automated tests on website functionality to catch when features have broken, the site has gone down, etc.

• Get a user's PTO allowance or fill out a PTO request in a portal that doesn't have API access to do so

• Enhance IT device management by logging into (often very primitive) web interfaces of IP-enabled printers, phones or projectors to obtain their configuration, ink levels or error messages

• Obtain balances for public transit cards, cafeteria pre-payment cards or copier credit cards which often offer a very basic web view of that information

• Fill out any kind of form, i.e. to order stationary, catering, automated error reporting, instantly submitting compliance notices

• Get a coworker's personal information from the employee directory that isn't accessible via API, i.e. their hobbies, expert skills, license plate, group memberships or users they follow

• Update a user's name (for example after a name change) across many different applications in one go

• Register an employees details with a loyalty or rewards program from airlines, taxi companies, shopping malls, etc.

• Get a user's photo from the Employee Directory to automatically upload it as an avatar to all their other applications, i.e. intranet, company chat, project management, collaboration tools for a more personal look for these applications

How do I start using a RESTful API?

Using APIs is usually reserved for developers. However some very popular APIs have their own interactive playgrounds you can use to explore endpoints and see JSON responses (the standard format for APIs).

Some examples exist from Microsoft, Alfresco or TomTom.

For anyone else you'd be best off getting acquainted with Postman. It's the universal API connection and debugging tool used by everyone. In Postman you can connect to any API using the query strings found in the respective documentation. The query string (highlighted) looks similar to a website URL, but it differentiates between your request being to GET or POST something from/to the API.

Many APIs also require you authenticate yourself with the API before you get a response. If that is required, such details will be found in their documentation. In Postman this is done by either entering Params (like a shared key) or by providing Authorization in the form of a token.

What's the difference between GET, PUT and POST?

RESTful APIs are mainly called through three different functions, called GET, PUT or POST requests.

1. GET calls are telling the server to return a certain range of data, formatted as JSON. These returns are read-only, so they're used to obtain information. An example would be: Send me a list of the 25 most recent tickets.

2. PUT requests are used to update existing entities in the source. So for example you could tell the server to "update user Id 47897 telephone number to (555) 478-9774"

3. Lastly a POST request is used to create a new child resources underneath an already existing resource. An example would be: Create a record for a new customer called 'Windmill Inc.' with their location at 100 Federal Ave.

How do I build a service with my RESTful API?

If you're a developer you know how to create your own functions that call APIs whenever your app or service need to. But if you aren't a full stack developer, what are things you could more or less easily build with your REST API? Here is some inspiration for API use cases that don't require a backend developer:

1. Show the API data in SharePoint

At a very simple level you could just build a Microsoft Adaptive Card that shows the data from this API, say to project it into your company intranet. Check out this step-by-step tutorial specifically to build an Adaptive Card for SharePoint.

Embed Adaptive Cards straight into a SharePoint site with a dedicated Webpart

2. Make a chatbot that calls the API data

Although this is crossing over into developer territory, you could make a chatbot that calls your API. Whilst you will need to do some programming, at least you could just have the chatbot be hosed in MS Teams or Slack, taking at least one variable out of the equation. We have made a few tutorials on how you can make your own chatbot using a RESTful API with Watson Assistant, Dialogflow or Botpress so check them out if this is of interest to you.

If you're just getting started with chatbots for your organization, here's another good primer that contains everything you need to know to build great chatbots for your internal use cases.

3. Build a persistent Card for your personal Dashboard

You could make a few different lists using APIs from different services and unite them under a single dashboard that shows you all of your lists under a single pane of glass. A popular and free tool do this could be Digital Assistant where every user gets a personal dashboard they can rearrange as they see fit.

4. Make RPA recipes

Zapier supports APIs as either a trigger for "recipes" (left) or as a step within a recipe (right)

Popular automation tools like PowerAutomate or Zapier already support hundreds of APIs straight out the gate, but even so they offer custom building blocks that allow you wait for an API trigger (called Webhook) or update data via an API POST calls.