Understanding Swagger Operations: A Guide to RESTful API Interactions

As we add more operations to our API, Paul Kelly looks at how Swagger can help you. In this blog he explain the seven different types of Swagger, what they do, and how you might use them.

“You want the moves like swagger, I got the moves like swagger, I got the mooooooves like swagger”.  Sorry I can’t help myself. Every time I hear or see the name Swagger that Maroon 5 song rings through my head.

Now if you reading this and thinking what’s he on about and what is Swagger, isn’t the line “moves like Jagger”. Well it is, but writing an N‑central blog about Maroon 5 or Mick Jagger wouldn’t make a whole lot of sense. Swagger, on the other hand, for those of you who don’t know is a powerful and widely adopted tool for building, documenting, and interacting with REST APIs.

By providing clear and interactive API documentation, Swagger improves the overall development process, boosts collaboration, and reduces complexity for developers working with APIs. It’s so widely adopted that every API that I’ve looked at recently, is using it—from N‑central to FortiGate to DNS Filter. What I’ve noticed particularly in N‑central is that as we add more and more operations to our API, we are seeing more and more types of Swagger operations being used. The operation in particular that triggered the idea for this blog was the addition of a Patch operation for Lifecycle-info. I was thinking to myself, what has Patch got to do with warranty info? Then I realised it was a term used by Swagger.

So in this blog I’m going to explain the seven different types of operations you will see in Swagger, what they do, and how you might use them.

First, a bit of context: Swagger organizes API operations by HTTP methods—GET, POST, PUT, DELETE, PATCH, OPTIONS and HEAD. Each of these operations serves a specific purpose when interacting with resources in a web service. Let’s take a closer look at what these methods do and when to use them.

1. GET (Blue): Retrieving Data

The GET method is the most common operation in any API. It is used to retrieve data from a server without altering anything on the server side.

• What it does: The GET operation fetches information, such as retrieving a list of devices or the details of a specific resource.
• Example Usage: Think of it as browsing a product catalog. You’re viewing the information but not changing or buying anything yet.

2. POST (Green): Creating New Resources

The POST method is used when you need to send data to the server to create a new resource.

• What it does: With a POST request, you are adding something new to the system, whether it’s a new user, a new customer, or a new maintenance window.
• Example Usage: It’s like filling out and submitting a form to create an account on a website.

3. PUT (Yellow): Updating an Entire Resource

When you need to update an existing resource entirely, the PUT method comes into play.

• What it does: PUT replaces the entire resource with the new data provided in the request body.
• Example Usage: Imagine editing a custom device property, this would overwrite all the current information with the new details you supply.

4. PATCH (Light Green): Partially Updating a Resource

Unlike PUT, which updates the entire resource, the PATCH method is used to update only part of a resource.

• What it does: PATCH allows you to modify specific fields without changing the entire resource.
• Example Usage: Let’s say you only want to update a devices warranty expiry date but leave everything else unchanged, that’s where PATCH shines.

5. DELETE (Red): Removing a Resource

The DELETE method is used to remove a resource from the server.

• What it does: As the name suggests, DELETE deletes a specific resource.

• Example Usage: Deleting a user from the system permanently.

6. OPTIONS (Grey): Discovering Supported Methods

Sometimes, before interacting with an API, you need to know what methods are available for a given endpoint. That’s where the OPTIONS method comes in handy.

• What it does: OPTIONS returns the HTTP methods (like GET, POST, PUT, etc.) that are allowed for a particular resource.
• Example Usage: Before making a request, you can use OPTIONS to discover what actions are supported by the API for a given endpoint.

7. HEAD (Purple): Checking Metadata Without the Body

The HEAD method works like GET, but it only retrieves the headers of the response, without the actual body content.

• What it does: HEAD is useful for checking if a resource exists or getting metadata like content length, without needing to download the full data.
• Example Usage: It’s like checking if a file is available for download without actually downloading it.

At the time of writing this, (October 2024), you will only see the first four operations in use in the N‑central API, but you are likely to see all of these operations as you expand your interaction with APIs across multiple solutions.

If you haven’t been using APIs up to this point, hopefully this blog will help you understand a bit more how APIs work, so you can do more with the products you use. If you have questions on this or anything else, please join me on the N-Central Office Hours or check out the REST APIs in N‑central Boot Camp on the N‑able U YouTube channel here.

Paul Kelly is the Head Nerd at N‑able. You can follow him on Twitter at @HeadNerdPaul, LinkedIn and Reddit at u/Paul _Kelly. Alternatively you can email me direct.