MuleSoft from Start: A Beginner’s Guide — Session 2: What is an API?
In the last session, we learned about the MuleSoft overview of products. We didn’t do a deep dive into them, but we learned that the main products are
- Anypoint Platform
- Anypoint Studio
- Composer
- MuleSoft RPA
- DataWeave
We also took a look at the community overview like the Ambassadors, Mentors, Meetups, and Help Center.
In this week’s session, we focused on understanding the basics of APIs and learning more about MuleSoft’s API-led connectivity approach. Let’s see a summary of what we learned!
Note: The links and some notes from the session have been added to the GitHub repository for you to follow through with what I’m doing in the video. You can find both recordings (the complete and the shorter one) at the end of the post.
Understanding APIs
Because I had already written a series of blog posts about simplifying your road to learning the basics of APIs, I referenced those posts when explaining them. In the GitHub repo, or here, you can find the links to read them on your own if you still have questions or want some further clarification.
Part 1: What is an API?
The way that I look at APIs is something like the following diagram.
You, as a client consuming the API, don’t really care about how the API is really working. You don’t care about the programming language it’s written in or what tech stack it’s using. You only care about what you can send in and what it returns back.
Whatever you send into the API is a request and whatever it returns back to you is a response. In the request, you send your input data along with the data type and the operation (what you want the API to do with the input data). In the response, you get some output data along with its data type.
Part 2: Analogies and Examples
Restaurant
In this analogy, you are the client. You arrive at this restaurant and take the menu to see the list of available food. You request the server to give you a hamburger. At this point, you don’t know exactly what the server is doing to make sure you get your order right. They may be writing the order down to pass to the kitchen, they may input your order in the computer, or whatever they do — you just care about getting your food exactly how you asked for it. After some time, the server comes back and gives you your order in response to your request.
Calculator
In this analogy, you input two numbers: 2 and 2; and select the addition (+) operation. After you press the equals button, the calculator does its thing and returns 4. Again, you don’t care much about what’s inside the calculator or what it does to give you the result. You just care about getting the correct result.
Human Resources system
First, you send the following request to your HR system with some CSV data. You ask the API to retrieve the listed employees’ first day of employment.
The HR API returns the same CSV information you had previously sent, but now adding a new field called First Day.
In the following picture, we can appreciate the same example, only using a JSON data type instead of a CSV data type.
Part 3: What are HTTP Methods?
There are 9 HTTP methods: GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, and PATCH. However, the most popular ones are GET, POST, PUT, PATCH, and DELETE.
- GET: Read or retrieve data from the server or the API.
- DELETE: Delete data from the server.
- POST: Create new data. Sending the same information more than once can result in duplicated data.
- PUT: Update or replace existing data. It can also be used to create new data. Sending the same information more than once will have the same effect as sending it just once.
- PATCH: Update or modify parts of existing data.
Whether you’ll be using POST or PUT to create new data is really up to you. These are just Mozilla’s standards. It is recommended that you follow them for the comfort of other developers using your API, but the design decision is really up to you.
Part 4: What is a URI?
If we take this URI as an example: https://official-joke-api.appspot.com/random_joke, we can separate the parts of this URI into the following.
…And that’s all that we need to understand from this post! 😃
Part 5: Intro to Postman and Query Parameters
If you go to the following link: https://www.google.com/search?q=cats, you are basically searching for cats in Google. Notice how there’s a ?q=cats after the path of the URI. This is our query parameter.
Take a look at a more complex example from Expedia which contains more query parameters:
https://www.expedia.com/Hotel-Search?adults=2&d1=2020-11-23&d2=2020-11-24&destination=Toronto%20%28and%20vicinity%29%2C%20Ontario%2C%20Canada&endDate=2020-11-24®ionId=178314&rooms=1&semdtl=&sort=RECOMMENDED&startDate=2020-11-23&theme=&useRewards=false&userIntentWe can put this URI in Postman to see a more human-readable list of all the query parameters we have here.
Part 6: What are HTTP Status Codes?
So far we have been focusing on the request part. Now, let’s see what other data can be returned in the response.
There are a lot of Status Codes reserved for certain API Responses, but we will be looking at the most popular ones: 200, 201, 202, 204, 400, 401, 403, 404, and 500. You can find a complete list here with their definitions.
- All status codes starting with 2 mean that the process was a success. Like 200 OK or 201 Created.
- Status codes starting with 4 mean that there was an issue with your request. Like 400 Bad Request or 404 Not Found.
- Status codes starting with 5 mean that there was an issue from the server side and not with your request. Like 500 Internal Server Error.
And that is all for learning about APIs! Now let’s take a look at what is API-led connectivity in MuleSoft.
What is API-led connectivity?
This is an architectural approach that we tend to do with the APIs we design using MuleSoft. There are three layers to this approach: Experience, Process, and System APIs.
- Experience layer: Top layer. These APIs connect with the client applications like a Mobile app, a Web app, or a Smartwatch app.
- Process layer: Middle layer. These APIs orchestrate the Experience and System layers.
- System layer: Bottom layer. These APIs connect with the server applications or third-party systems like SAP, Facebook, Salesforce, etc.
Recordings
Finally, here are the two recordings you can find about this session.
Here you can find the shorter version from YouTube:
And here you can find the complete video from Twitch:
Please let me know if you have any comments, suggestions, or just general feedback for me!
