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.
--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
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
This option is used to set headers to requests.
curl --request POST \
--url http://localhost:5000/api/data \
--header 'content-type: application/json'
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"}'
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
- 6 - Can't resolve host
- 7 - Couldn't connect to hose
- 28 - Operation timeout
- 55 - Failed to send data
- 56 - Failed to receive data
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
mkdir test_curl_app
npm install -g express-generator
cd test_curl_app
express curl_app
- In the generated package.json, you can remove 'cookie-parser'
npm install --save cors
npm install -g nodemon
- 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"}]}