cURL tool usage, tips, and usage as an alternative to Postman

curl_tool_usage.md

cURL tool usage, tips, and usage as an alternative to Postman

cURL is a transfer tool used to transfer data from or to a server. It supports various internet protocols of transfer, including: DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET and TFTP. Using cURL one can perform useful tricks with cURL like proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume, Metalink, and more.

cURL options

--request or -X

--request and -X specify a custom request method you can use when communicating with the HTTP server. The specified request method will be used instead of the method otherwise used (which defaults to GET).

To perform a POST request:

curl --request POST

To perform a GET (cURL defaults to GET) request:

curl --request GET

--url

This specifies the URL that we will be fetching or transferring data to. If the given URL is missing a scheme name (such as “http://, “ftp://, etc) then cURL will make a guess based on the host. If the outermost subdomain name matches DICT, FTP, IMAP, LDAP, POP3, or SMTP, then that protocol will be used. Otherwise, HTTP will be used.

GET example:

curl --request GET --url https://moviesdb.com/movies/all

POST example:

curl --request POST --url http://localhost:3000

--header or -H

This option is used to set headers to requests.

curl --request POST \
  --url http://localhost:5000/api/data \
  --header 'content-type: application/json'

--data or -d

This option is used to send data to an server. This can be used in POST requests to send data to the server.

Example:

curl --request POST \
  --url http://localhost:5000 \
  --header 'content-type: application/json' \
  --data '{"name":"Joe","description":"description","rating":"2.0","image":"joedirt.png"}'

Other cURL options

Option	Description
-v	verbose
-s	hide progress
-S	when used with -s, shows errors
--compressed	gzipped response
-k	insecure https
-A "string"	user-agent
-x <host:port>	use proxy
-o	output to file
-O	writes output to file instead of stdout
-m	timeout
--connect-timeout	maximum time allowed to connect to server
-u user:password	basic authentication
-H "name:"	remove a header
-w "format"	extra information
-d "string", -d @file	POST method
-T <file>	PUT method
-l	HEAD method
-b <cookiejar>	read cookie jar
-c <cookiejar>	write cookie jar
-b "c=1;d=2"	send cookies
-L	follow redirects
-F name=value, - Fname=@file	multi-part formpost
--data-binary @<filename>	does not process file before sending
-d	sends data as ASCII
--cert, --key	use a client certificate

• The cookiejar is a file that curl will write cookies to after a completed operation.
• The -w, write out option defines what to display on stdout after a completed and successful operation. Example: curl -w "Type: %{content_type}\nCode: %{response_code}\n" http://example.com

cURL Exit Codes

• 6 - Can't resolve host
• 7 - Couldn't connect to hose
• 28 - Operation timeout
• 55 - Failed to send data
• 56 - Failed to receive data

An alternative to Postman

While Postman is a useful tool for setting up and testing API endpoints, depending on the environment, or requirements, Postman might not be available.

Setup an Express.JS application

1. mkdir test_curl_app
2. npm install -g express-generator
3. cd test_curl_app
4. express curl_app
5. In the generated package.json, you can remove 'cookie-parser'
6. npm install --save cors
7. npm install -g nodemon
8. You can remove the routes directory, and index.jade under views/

In the package.json, you can replace the scripts section with:

"scripts": {
  "start": "nodemon app.js",
  "clean": "rm -rf node_modules",
  "rebuild": "rm -rf node_modules && npm install && nodemon start"
},

Replace the app.js code with:

const createError = require("http-errors");
const express = require("express");
const path = require("path");
const logger = require("morgan");
const cors = require("cors");

const apiRouter = express.Router();

const app = express();

// view engine setup (for errors)
app.set("views", path.join(__dirname, "views"));
app.set("view engine", "jade");

app.use(logger("dev"));
app.use(express.json());
app.use(cors());

let users_db = [];
let currId = Date.now();

apiRouter.get("/user/:id", (req, res, next) => {
  const userId = req.params.id;
  const users = users_db.filter((user) => String(user.id) === String(userId));
  if (users.length > 0) {
    res.send({ user: users[0] });
  } else {
    res.send({ mesg: "No user found." });
  }
});

apiRouter.get("/users", (req, res) => {
  res.send({ users_db });
});

apiRouter.post("/user", (req, res) => {
  let reqbody = req.body;
  reqbody = { id: ++currId, ...reqbody };
  users_db.push(reqbody);
  res.send({ user: reqbody });
});

app.use("/api", apiRouter);

// catch 404 and forward to error handler
app.use(function (req, res, next) {
  next(createError(404));
});

// error handler
app.use(function (err, req, res, next) {
  // set locals, only providing error in development
  res.locals.message = err.message;
  res.locals.error = req.app.get("env") === "development" ? err : {};

  // render the error page
  res.status(err.status || 500);
  res.render("error");
});

app.listen(3000, () => {
  console.log(`Server started at port: 3000`);
});

and then to run the application:

npm install rebuild

finally to test cURL against the API endpoints:

curl --request POST \
  --url http://localhost:3000/api/user \
  --header 'content-type: application/json' \
  --data '{"name": "Willy Wonka", "age": "56"}'

{"user":{"id":1608849531656,"name":"Willy Wonka","age":"56"}}

curl --request POST \
  --url http://localhost:3000/api/user \
  --header 'content-type: application/json' \
  --data '{"name": "Duff McKagan", "age": "55"}'

{"user":{"id":1608849531657,"name":"Duff McKagan","age":"55"}}

curl --request GET \
  --url http://localhost:3000/api/user/1608849531656

{"user":{"id":1608849531656,"name":"Willy Wonka","age":"56"}}

curl --request GET \
  --url http://localhost:3000/api/user/1608849531657

{"user":{"id":1608849531657,"name":"Duff McKagan","age":"55"}}

curl --request GET \
  --url http://localhost:3000/api/user/2000000000

{"mesg":"No user found."}

curl --request GET \
  --url http://localhost:3000/api/users

{"users_db":[{"id":1608849531656,"name":"Willy Wonka","age":"56"},{"id":1608849531657,"name":"Duff McKagan","age":"55"}]}