Working with Web APIs
An API, or Application Programming Interface, lets developers interface with data without having to access the data directly. Web APIs let you do this by making requests to servers. APIs can let you see current weather conditions, stock prices, sports scores, social media feeds, and pretty much any data you’re looking to consume.
If you’re writing software that interfaces with a third-party web API, or if you’re developing your own, you can use cURL to explore and test that API. You can set headers, define request types, and send data payloads.
To explore this, you’ll need an API you can work with. Instead of using a live API for testing, you’ll use json-server,[24] a Node.js package that provides an API for these types of situations. Let’s set it up inside of the Ubuntu virtual machine.
First, install Node.js on your Ubuntu virtual machine. You’ll need Node.js to run json-server. The Node.js package available through Ubuntu’s packages is out of date, but you can use the NodeSource repository[25] to get a more recent version.
First, use curl to download an installation script from Nodesource that adds their repository to your system and updates the list of available packages.
First, download the installation script:
| | $ curl -L -O https://deb.nodesource.com/setup_11.x |
Then, review the script to learn what it does and how it works. Never run scripts that you download from the Internet until you have inspected their contents:
| | $ less ./setup_11.x |
Now execute the installation script and install the nodejs package:
| | $ sudo bash ./setup_11.x |
| | $ sudo apt install nodejs |
This installs Node.js, along with npm, a command for installing Node.js libraries and programs, and npx, a command which downloads and then executes applications.
Now, create a JSON file in your home directory called data.json with the following content:
| | { |
| | "notes": [ |
| | { "id": 1, "title": "Hello" } |
| | ] |
| | } |
json-server will use this as its data and turn it into a REST API you can query. You can use nano to create it, or create it with cat:
| | $ cat << 'EOF' > ~/data.json |
| | > { |
| | > "notes": [ |
| | > { "id": 1, "title": "Hello" } |
| | > ] |
| | > } |
| | > EOF |
With the file created, use the npx command to run json-server and tell it to watch the data.json file for changes:
| | $ npx json-server -w ~/data.json |
The files download and the server starts, displaying information about how to connect to the web API:
| | {^_^}/ hi! |
| | |
| | Loading data.json |
| | Done |
| | |
| | |
| | Resources |
| | http://localhost:3000/notes |
| | |
| | Home |
| | http://localhost:3000 |
| | |
| | Type s + enter at any time to create a snapshot of the database |
| | Watching... |
Open a new terminal window so you can make some requests to the server with cURL.
In your new terminal window, make a request to http://localhost:3000/notes and you’ll see the notes you created in the data.json file appear on the screen:
| | $ curl http://localhost:3000/notes |
| | [ |
| | { |
| | "id": 1, |
| | "title": "Hello" |
| | } |
| | ] |
Now that you know the API is responding, and that you can use cURL to fetch data, let’s use cURL to add a new record to this API. To do that, you’ll need to make a POST request, specify headers, and specify the data you want to send:
| | $ curl -X POST http://localhost:3000/notes |
| | > -H 'Content-type: application/json' |
| | > -d '{"title": "This is another note"}' |
The -X POST argument specifies that you want a POST request. The -H flag sets a request header that tells the server that you are sending JSON data. The -d argument specifies the data that you are sending, which is the JSON for the new note.
You’ll see the new record returned from the API, letting you know you added the record:
| | { |
| | "title": "This is another note", |
| | "id": 2 |
| | } |
Verify this by requesting the notes resource again:
| | $ curl http://localhost:3000/notes |
| | [ |
| | { |
| | "id": 1, |
| | "title": "Hello" |
| | }, |
| » | { |
| » | "title": "This is another note", |
| » | "id": 2 |
| » | } |
| | ] |
You can delete that note with cURL as well:
| | $ curl -X DELETE http://localhost:3000/notes/2 |
To stop json-server, switch back to its terminal window and press Ctrl+c.
cURL is an invaluable tool in your tool belt as a developer. You can use it to drive the development of your API before you write the client, and you can use it to document how others can use your API.
Ready to look at connecting to servers or other machines using SSH?