Lab 11 - Nautobot ReST APIs

Lab Overview

This lab is all about interacting with Nautobot's ReST APIs. We'll be using Swagger's interactive API documentation for submitting requests, viewing responses and understanding expected behavior. We will also take a look at the Django Rest Framework browsable API.

Table of Contents

Lab 11 - Nautobot ReST APIs

• Task 1 - Docs
  • Step 1-1 - Login via the web browser to Nautobot
  • Step 1-2 - Open Swagger
  • Step 1-3 Review the Swagger GUI
• Task 2 - GET requests
  • Step 2-1 Submit a GET request
  • Step 2-2 Submit a GET request with parameters
  • Step 2-3 Submit a GET request for a specific object
• Task 3 - POST Requests
  • Step 3-1 Submit a POST reqeust
• Task 4 - PATCH Requests
  • Step 4-1 Submit a PATCH reqeust
• Task 5 - DELETE Requests
  • Step 5-1 Submit a DELETE reqeust
• Task 6 - Django REST Framework Browsable API
  • Step 6-1 Browse from the API Root
• Task 7 - Authenticate using a Token
  • Step 7-1 Create a token from the Nautobot Admin
  • Step 7-2 Make a GET request with cURL

Task 1 - Open and review the Swagger interface

Step 1-1 - Login via the web browser to Nautobot

If you have not already, use a web browser to navigate to your instance of Nautobot at https://{{ your pod }}. Log into Nautobot by using the login option in the upper right of the Nautobot homepage. You can log in as the superuser you created in a previous lab or the superuser account included with your lab environment, the credentials for this account will be provided by the instructor.

Step 1-2 - Open Swagger

From the Nautobot homepage, click on the API link in the bottom right corner to open Swagger.

It will take a few moments to load.

Once loaded, you will be presented with header, indicating that you are looking at the API Documentation, and a long list of API endpoints for all the supported objects within Nautobot.

Step 1-3 Review the Swagger GUI

At the top of the page there is a Base URL. This is the root for all Nautobot API requests. By adding to the base URL we can make requests for specific information from Nautobot, filter those requests and even make changes and add new information.

If you navigate to https://{{ your pod }}/api/ in a browser you will see the Django Rest Framework respond with a user-friendly representation of the API, complete with links for navigation. We will take a look at the Django Rest Framework browsable API later, for now let's continue with Swagger.

Here are the REST HTTP verbs available for use and what they do:

GET - Retrieve information, nothing is changed in the database.

POST - Create a new object in the database.

PUT - Modify an existing object by sending, at a minimum, all required fields.

PATCH - Modify an existing object by sending only the new, updated information.

DELETE - Delete an object from the database

Scroll down the list (or use CTRL+F) to find this endpoint: /dcim/platforms/

Click anywhere on the blue GET request bar for /dcim/platforms/ to open the options and information regarding GET requests to that endpoint. When expanded, the Parameters will appear at the top. These are the fields and lookup expressions that can be used to search all Platform objects. This particular endpoint is for all Platforms, so none of the fields is required. However, if we were using this endpoint, /dcim/platforms/{id}, and id would be required.

The double underscores, followed by characters, represent lookup expressions. For example this __iew means case-insensitive ends with. So name__iew, would attempt to match the search string to the end of the name field. The filtering documentation can be found at https://docs.nautobot.com/projects/core/en/stable/rest-api/filtering/ and, I've listed the common expressions below.

Numeric Fields:

n - not equal to (negation)
lt - less than
lte - less than or equal
gt - greater than
gte - greater than or equal

String Fields:

n - not equal to (negation)
ic - case-insensitive contains
nic - negated case-insensitive contains
isw - case-insensitive starts-with
nisw - negated case-insensitive starts-with
iew - case-insensitive ends-with
niew - negated case-insensitive ends-with
ie - case-insensitive exact match
nie - negated case-insensitive exact match

Scroll down to find the Responses section. Here we can see the expected response to a successful get request. The response example is json with a response code of 200.

Task 2 - GET requests

Step 2-1 Submit a GET request

Scroll back to the top of the GET request box for the /dcim/platforms/ endpoint. Look for the Try it out button on the top right and click it. This will unlock all the parameters and allow us to send a request to Nautobot. For this first request, don't bother adding any parameters just scroll back to the bottom and click the big blue Execute button.

There isn't a large number of Platforms, so it should only take a moment to see the response. The response is shown in the Responses box and now contains a curl command that can be used to make the same request, and the URL used in the request.

Please note, if you copy and then paste the curl command into a terminal, it will fail because the command does not contain authentication. We are logged into Nautobot right now, so our requests are authenticated, but if we wanted to make requests from outside Nautobot, we would need a token. We will try that out later.

A total of 8 objects are in the response, and for each one, all the data is returned. Unlike GraphQL, we cannot specify exactly what we want in the response. However, the ReST API supports writing to the database, while Nautobot's GraphQL endpoint does not.

Step 2-2 Submit a GET request with parameters

Scroll back up to the Parameters box and add a Manufacturer. Type cisco into the box and click Execute again. Note that we need to use the slug when looking up a Manufacturer using a string.

Only 5 objects have been returned and note that the Request URL and curl command have been updated to reflect the included parameters.

Step 2-3 Submit a GET request for a specific object

Look for the id value for one of the Platforms in the response, it doesn't matter which one. This is the UUID that uniquely identifies the object in the database. Copy it to the clipboard. I will be using 4ed07c46-bac1-4ef7-8f4d-14747b98a63d but the id values in your response will be different, so be sure to copy one of those.

Scroll down and look for the blue GET request box for this endpoint /dcim/platforms/{id} and expand it just like we did before. Right at the top you'll notice there is a required parameter, the id. In fact, that is the only parameter! There is no need to filter if you know exactly what you want.

Click Try it out, paste the id in and click Execute. Only 1 object is returned and the id is now part of the curl command and the Request URL.

Task 3 - POST Requests

A POST request will create new objects in the database.

Step 3-1 Submit a POST reqeust

We are going to create a new Rack for our stadium. Locate the POST endpoint for Racks in the Swagger API documentation, and expand the dialogue box by clicking on the green bar.

The Request body is required, but what fields are required in the body? Let's check the schema, click on Schema next to Example Value. The red asterisks indicate that name, site and status are required. Slug isn't strictly required because it will be generated for us.

Click on the Try it out button to reveal the sample request body format. The site and tenant objects are referenced via UUID. We could get those ids from right here in the API documentation, but since we know exactly what we want, let's just go get it from the detail pages for those objects in Nautobot.

Open a new tab and go to the detail page for your stadium's Site, and click the Advanced tab. If you then hover your mouse over the UUID a copy button will appear. Copy the UUID and save paste it to a text file for use in our request. You could also just come back here and get the ids when you are creating the request.

Also retrieve the UUID for the Nautobot Football Stadiums Tenant.

Here is an example request body for a new rack. Not all this data is required, but it gives you an idea of what a POST body might look like.

{
  "name": "hou01-102",
  "site": "1201575f-e882-4c68-99c5-1a575d021391",
  "tenant": "3696728f-ac12-45ab-ba9f-c134cce8e1ce",
  "status": "planned",
  "type": "4-post-frame",
  "width": 19,
  "u_height": 48
}

Click Execute to send the request. If successful, the response status code will be 201 (for created) and the new Rack object will be returned.

Task 4 - PATCH Requests

Step 4-1 Submit a PATCH reqeust

Unlike a PUT request, PATCH requests allow objects to be updated without sending the entire representation of an object in the request.

Copy the id of the new Rack and scroll down to the PATCH endpoint for a specific Rack.

Make a small change, in my example I am updating the status and execute the request. Don't forget to paste in the id!

If the PATCH was successful, the object will be returned with a status code of 200.

Task 5 - DELETE Requests

Step 5-1 Submit a DELETE reqeust

Scroll down just a little further and find the DELETE request for racks, /dcim/racks/{id}. Try it out by deleting the new Rack we just created.

Up to this point all the requests we've made have returned the object being created or modified, however there is nothing to return with a successful DELETE, so we just get a status code of 204 back.

Task 6 - Django REST Framework Browsable API

Step 6-1 Browse from the API Root

Navigate to https://{{ your pod }}/api/ to open the browsable API. From here, simply click on any URL to follow the API through to a list of objects or individual object.

Click on the URL next to dcim and then sites. A list of all the Sites in Nautobot are returned.

Click on an individual Site to see the details for just that Site.

You can even filter if you put the correct parameters into the URL. Once you are familiar with using the API in Swagger, this can be faster for a quick search. Try this URL (substitute for your Site name if necessary):

https://{{ your pod }}/api/dcim/sites/?name=HOU01

Task 7 - Authenticate using a Token

Step 7-1 Create a token from the Nautobot Admin

Previously I mentioned that a token would be needed for making API requests from outside Nautobot. Let's create a new token from the Admin and use it for a request.

From the Nautobot homepage, click on the drop-down menu in the upper right that is labeled with the logged-in username, and select Admin.

From the Admin page, select Token under the Users section to open the list of available Tokens. There are a number of Tokens already available, click the Add button to create a new one.

The only required field is a User to assign the key to. Optionally, an expiration date/time and description can be provided. Select your User, and click Save.

The new Token will appear at the bottom of the list. Either keep this tab open, or copy the Token because we will need it in the next step.

Step 7-2 Make a GET request with cURL

In the example below, curl is being used along with the new Token. The Token needs to be in the Authorization header and should contain the word Token along with a space followed by the Token. Try changing the endpoints to get different data back.

curl -H "Authorization: Token 9eb51a5ed7544aff7e6669136023824083ea2f01" -H "Accept: application/json; indent=4" https://pub11-pod01.cloud.networktocode.com/api/dcim/devices/ --insecure

Response:

{
    "count": 439,
    "next": "https://pub11-pod01.cloud.networktocode.com/api/dcim/devices/?limit=50&offset=50",
    "previous": null,
    "results": [
        {
            "id": "ca3a9003-b6ac-4e9a-b3f9-3f7e402445d6",
            "display": "ams01-dist-01",
            "url": "https://pub11-pod01.cloud.networktocode.com/api/dcim/devices/ca3a9003-b6ac-4e9a-b3f9-3f7e402445d6/",
            "name": "ams01-dist-01",
            "device_type": {
                "display": "Cisco Catalyst 6509-E",
                "id": "7fc659b6-7d25-43be-805e-253a9aaae85e",
                "url": "https://pub11-pod01.cloud.networktocode.com/api/dcim/device-types/7fc659b6-7d25-43be-805e-253a9aaae85e/",
                "manufacturer": {
                    "display": "Cisco",
                    "id": "836fd120-b128-4994-b9e3-aa69736a8875",
                    "url": "https://pub11-pod01.cloud.networktocode.com/api/dcim/manufacturers/836fd120-b128-4994-b9e3-aa69736a8875/",
                    "name": "Cisco",
                    "slug": "cisco"
                },
                "model": "Catalyst 6509-E",
                "slug": "catalyst-6509-e"
            },
            "device_role": {
                "display": "distribution",
                "id": "b51a00c3-338e-4dc6-b856-71630f1a9ba9",
                "url": "https://pub11-pod01.cloud.networktocode.com/api/dcim/device-roles/b51a00c3-338e-4dc6-b856-71630f1a9ba9/",
                "name": "distribution",
                "slug": "distribution"
            },
            "tenant": {
                "display": "Nautobot Airports",
                "id": "cd3f6bbd-e2d7-49cd-885f-49b352326a7b",
                "url": "https://pub11-pod01.cloud.networktocode.com/api/tenancy/tenants/cd3f6bbd-e2d7-49cd-885f-49b352326a7b/",
                "name": "Nautobot Airports",
                "slug": "nautobot-airports"
            },
            "platform": {
                "display": "Cisco IOS",
                "id": "6b70599a-6b04-4e53-ba4b-cdcc2259e237",
                "url": "https://pub11-pod01.cloud.networktocode.com/api/dcim/platforms/6b70599a-6b04-4e53-ba4b-cdcc2259e237/",
                "name": "Cisco IOS",
                "slug": "cisco_ios"
            },
            ...