Part 1 – Decoding API docs

Welcome.

I want to make this mini-course as compact and practical as possible, so we will not get into the whole history of what API was doing back in the 90s as a young, undisciplined kid. 

My aim is to give you the most in the shortest.

We’ll use Loop’s API doc, to quickly understand 

• what is where,
• what is what,
• why is what.

Open it so you can follow along.

Most modern mailers have similar documentation, and through this, you’ll understand what to copy, paste, fill and twiddle.

(And Loop has dark mode, so my eyes won't turn into pudding. You can also switch Isit into calming darkness if you wish to. Click on the moon below to do that.)

Basic concepts

What is API? Why is it resting? That lazy dick.

Imagine that you are in a cheerful bandit camp in a thick unwelcoming forest. You - being one of the smelly, hairy brutes - need to hear the hot news, and exchange messages with your lowlife cousin strategically placed in the Inn at the Crossroads. 

So - smartly - you are using a fleet of dumb-looking pigeons, to carry your requests and bring back what you seek to know. That’s what API (Application Programming Interface) is. A pigeon. With a saddle. You, the thug (client) send the pigeon (API) to the Inn (server). You put the request (properties) into the saddle of the poor creature and train it to fly to the right window of the right Inn (this will be a specific URL from the doc). 

Now your cousin, as smart as ugly - wants to make sure that the message is from you - hence asking for the c.o.d.e. You know what when you were kids together throwing shit at the...anyway...the code is the API key.

The API key is hidden in a box inside the toilet

OK. The find the API key, log into your chosen email tool. It is usually within the settings, cleverly labelled as “API” or “Integrations”. With some (like in Brevo or Elastic Email) you generate a new one for each case, but for most, it's just one key.

Keep it hidden. Keep it safe. Frodo.

Some of the Terms:

like why your cousin is RESTing?

Because he is a lazy fucking buffoon. REST (Representational State Transfer) is an architecture, like a set of grammar rules to follow when you write to cousin, so even he understands it. That dumb turd. REST is based on standard HTTP requests.

Endpoints, Requests, Body and Responses.

By this point, your wisdom rivals of the druids of old, when it comes to API. So there is just a bit more. 

An endpoint is the address of the Inn, to the exact window, in the form of a URL. In our API doc, if you click on the Create contact tab on the left, on the right side you will see the specific URL endpoint - aka. address to the window - where this request (create me a contact, Cus) should be dropped. (eg. https://app.loops.so/api/v1/contacts/create )

Don’t ask how he will get into creating a contact, probably best not to imagine. To help you not imagine here is an image. 

The requests are the type of commands you can bark to that 5-word-vocabulary moron. You won’t believe what he did with the ... anyway. These can be: GET: Tell me something! (requesting data from the email tool) POST: Doooo it. Now! (Adding new data, like creating a subscriber)PUT/PATCH: Change it, you dumb shit! (Update existing data, like adding a tag, or changing a custom field for the contact). DELETE: Make it disappear, you creten. (like cancelling your order).

For the most part, you will use the Post (adding new subs) and the Update. Now if you click the different options in the doc (Create, Update, Find etc), you will see the Endpoint URLs and all the details you can add. Speaking of 

The message in the Saddle

This is where you tell Cousin what to do: name, look, beat up the poor fellow or just rob (yes/no) ... so all the fine details of the robbery. By the way, your cousin, that tool is called Jason. Spells it as Json because his front teeth were kicked out in a wedding by the priest.

In the middle of the doc, you will see the “Body”. 

Integers, if available means numbers. Some mailers give you the option to set up custom fields of different formats, in this case, a number would be some counting (like customer value) or lead scoring. 

Ok, let’s get back to JSON, and see what that disgrace might dare to send back to camp to your request. Remember, he is an untrustable fuck. 

Responses from Cousin

At this point, Cousin is probably drunk as a pig and will respond in single words. "success": false, - meaning he fucked it up, with some made-up excuse, like "message": “No can do. Too drunk. Lost clothes.” or in the unlikely case he does do it, that bonehead - he will send this: "success": true,

We’ll get to the common errors, but that may be mailer specific, and better treated by the doctors of their support.

Alrighty. Let’s give birth to this thing. 

Prepare your mailer’s API and some towels and hot water. 

(Have you noticed that in every TV show scene when they assist a birth, they order the guy to bring these two. Yet it’s never used. Why is it for then? Mystery.)