Search results

Use methods with curl

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

Our sample weather API doesn’t allow you to use anything but a GET method, so for this exercise, we’ll use the petstore API from Swagger but without actually using the Swagger UI (which is something we’ll explore later). For now, we just need an API with which we can use to create, update, and delete content.

In this example, using the Petstore API, you’ll create a new pet, update the pet, get the pet’s ID, delete the pet, and then try to get the deleted pet.

Create a new pet

To create a pet, you have to pass a JSON message in the request body. Rather than trying to encode the JSON and pass it in the URL, you’ll store the JSON in a file and reference the file.

A lot of APIs require you to post requests containing JSON messages in the body. This is often how you configure a service. The list of JSON key-value pairs that the API accepts is called the “Model” in the Swagger UI display.

  1. Insert the following into a next text file. This information will be passed in the -d parameter of the curl request:

    {
      "id": 123,
      "category": {
        "id": 123,
        "name": "test"
      },
      "name": "fluffy",
      "photoUrls": [
        "string"
      ],
      "tags": [
        {
          "id": 0,
          "name": "string"
        }
      ],
      "status": "available"
    }
    
  2. Change the first id value to another integer (whole number). Also, change the pet’s name of fluffy to something else.

    Use a unique ID and name that others aren’t likely to also use. Also, don’t begin your ID with the number 0.

  3. Save the file in a directory that you can conveniently access from your terminal, such as your user directory (on a Mac, Users/YOURUSERNAME — replace YOURUSERNAME with your actual user name on your computer).
  4. In your terminal, browse to the directory where you saved the mypet.json file. (Usually the default directory is Users/YOURUSERNAME — hence the previous step.)

    If you’ve never browsed directories using the command line, here’s how you do it:

    On a Mac, find your present working directory by typing pwd. Then move up by typing change directory: cd ../. Move down by typing cd pets, where pets is the name of the directory you want to move into. Type ls to list the contents of the directory.

    On a PC, just look at the prompt path to see your current directory. Then move up by typing cd ../. Move down by typing cd pets, where pets is the name of the directory you want to move into. Type dir to list the contents of the current directory.

  5. After your terminal or command prompt is in the same directory as your JSON file, create the new pet:

    curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d @mypet.json "http://petstore.swagger.io/v2/pet"
    

    The Content-Type indicates the type of content submitted in the request body. The Accept indicates the type of content we will accept in the response. The response should look something like this:

    {"id":51231236,"category":{"id":4,"name":"testexecution"},"name":"fluffernutter","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"}
    

    Check to see that your pet’s name was returned.

    Feel free to run this same request a few times more. REST APIs are "idempotent," which means that running the same request more than once won’t end up duplicating the results (you just create one pet here, not multiple pets). Todd Fredrich explains idempotency by comparing it to a pregnant cow. Let’s say you bring over a bull to get a cow pregnant. Even if the bull and cow mate multiple times, the result will be just one pregnancy, not a pregnancy for each mating session.

Update your pet

Guess what, your pet hates its name! Change your pet’s name to something more formal using the update pet method.

  1. In the mypet.json file, change the pet’s name.
  2. Use the PUT method instead of POST with the same curl content to update the pet’s name:

    curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -d @mypet.json "http://petstore.swagger.io/v2/pet"
    

Get your pet’s name by ID

Find your pet’s name by passing the ID into the /pet/{petID} endpoint:

  1. In your mypet.json file, copy the first id value.
  2. Use this curl command to get information about that pet ID, replacing 51231236 with your pet ID.

    curl -X GET --header "Accept: application/json" "http://petstore.swagger.io/v2/pet/51231236"
    

    The response contains your pet’s name and other information:

    {"id":51231236,"category":{"id":4,"name":"test"},"name":"mr. fluffernutter","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"}
    

    You can format the JSON by pasting it into a JSON formatting tool:

    {
      "id": 51231236,
      "category": {
        "id": 4,
        "name": "test"
      },
      "name": "mr. fluffernutter",
      "photoUrls": [
        "string"
      ],
      "tags": [
        {
          "id": 0,
          "name": "string"
        }
      ],
      "status": "available"
    }
    

Delete your pet

Unfortunately, your pet has died. It’s time to delete your pet from the pet registry.

  1. Use the DELETE method to remove your pet. Replace 5123123 with your pet ID:

    curl -X DELETE --header "Accept: application/json" "http://petstore.swagger.io/v2/pet/5123123"
    
  2. Now check to make sure your pet is really removed. Use a GET request to look for your pet with that ID:

    curl -X GET --header "Accept: application/json" "http://petstore.swagger.io/v2/pet/5123123"
    

    You should see this error message:

    {"code":1,"type":"error","message":"Pet not found"}
    

This example allowed you to see how you can work with curl to create, read, update, and delete resources. These four operations are referred to as CRUD and are common to almost every programming language.

Although Postman is probably easier to use, curl lends itself to power-level usage. Quality assurance teams often construct advanced test scenarios that iterate through a lot of curl requests.

Import curl into Postman

You can import curl commands into Postman by doing the following:

  1. Open a new tab in Postman and click the Import button in the upper-left corner.
  2. Select Paste Raw Text and insert your curl command:

    curl -X GET --header "Accept: application/json" "http://petstore.swagger.io/v2/pet/5123123"
    

    Make sure you don’t have any extra spaces at the beginning.

    Importing into Postman

  3. Click Import.
  4. Close the dialog box.
  5. Click Send. (If you deleted your pet, you’ll see the same “Pet not found” error message as before.)

Export Postman to curl

You can also export Postman to curl by doing the following:

  1. If desired, select one of your OpenWeatherMap API requests in Postman.
  2. Click the Code button (it’s right below Save).

    Generating code snippets

  3. Select curl from the drop-down menu.
  4. Copy the code snippet.

    curl -X GET \
      'https://api.openweathermap.org/data/2.5/weather?lat=37.3565982&lon=-121.9689848&units=imperial&appid=fd4698c940c6d1da602a70ac34f0b147' \
      -H 'Postman-Token: de0da6b7-1dbc-44d6-acc1-9741f05a7bf1' \
      -H 'cache-control: no-cache'
    

    You can see that Postman adds some extra header information (-H 'Postman-Token: de0da6b7-1dbc-44d6-acc1-9741f05a7bf1' \ -H 'cache-control: no-cache') into the request. This extra header information is unnecessary and can be removed.

  5. Remove the backslashes and line breaks. If you’re on Windows, change the single quotes to double quotes.
  6. Insert the curl command into your terminal and observe the result.

    curl -X GET "https://api.openweathermap.org/data/2.5/weather?lat=37.3565982&lon=-121.9689848&units=imperial&appid=fd4698c940c6d1da602a70ac34f0b147"
    

    Through Postman’s Import and Code functionality, you can easily switch between Postman and curl.

19% Complete

19/110 pages complete. Only 91 more pages to go...

Donate?

Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.