Call an HTTP API with curl: Creating, Updating, and Deleting Resources

The previous challenge used GET requests to read data from an HTTP API. In this challenge, you will practice sending requests that change data on the server: POST to create a resource, PUT and PATCH to update one, and DELETE to remove one.

The Artifact Inventory API is reachable from the workstation-01 machine at http://api.corp.internal:8080. Besides the read endpoints the previous challenge focused on, it offers the following ones:

POST /api/v1/artifacts - register a new artifact (JSON body with name, version, and platform)
PUT /api/v1/artifacts/<name> - replace the record of an artifact (JSON body with version, platform, status, and an optional description)
PATCH /api/v1/artifacts/<name> - change some fields of an artifact (JSON body with the fields to change)
DELETE /api/v1/artifacts/<name> - remove an artifact
PUT /api/v1/artifacts/<name>/manifest - upload the manifest of an artifact (the body is the manifest file)

Task 1: Change the Request Method

Before changing anything, practice changing the request method. Send an OPTIONS request to the /api/v1/artifacts/report-builder endpoint. The response will contain an Allow header that lists all supported methods.

Hint 1

The -X <method> option (or --request) sets the request method. An OPTIONS response has no body, so add -i to see the status line and the headers.

Task 2: Create a Resource with POST

Requests creating or modifying the data usually carry a body, and the server might need to be told what format the body is in. The curl command allows attaching the body and setting the Content-Type header for a request.

Note

A successful POST answers 201 Created, and the Location header of the response holds the URL of the new record. Use a GET /api/v1/artifacts/<name> request to retrieve back the just created artifact record - it is the easiest way to check your work.

Hint 2

The -d <data> option sends a request body and switches the method to POST (unless the method is not explicitly set). By default, curl labels such a body as a web form. This API wants JSON, so add a Content-Type: application/json header.

Or use the --json <data> option (instead of -d) - it sets the method, the body, and the header all at once.

Hint 3

The body is a JSON object with the three fields from the endpoint table. Put it in single quotes so the shell leaves the double quotes alone. For example:

curl -d '{"foo": 42}' <url>

If the server answers 400, its JSON error message names the field it did not like.

Task 3: Change One Field with PATCH

The report-builder artifact is being phased out. Mark it as deprecated by setting its status field to deprecated. All its other fields must keep their current values.

Hint 4

A PATCH request carries only the fields to change. The method is set with -X PATCH, and the body is a JSON object with a single field. The -X and -d options can be combined.

Task 4: Replace a Record with PUT

The log-shipper artifact got a new build. Replace its record with a new one: version 0.2.0, platform linux/arm64, status active, and the description Ships logs to the central store.

Hint 5

A PUT request replaces the whole record, so the body must contain every field of the new record. For example:

{"version":"0.2.0","platform":"linux/arm64","status":"active","description":"Ships logs to the central store"}

The server answers 400 and names the missing fields when the body is incomplete.

Task 5: Upload a File with PUT

The manifest of the new log-shipper build is in ~/log-shipper-manifest.json on workstation-01. Upload it to the manifest endpoint of log-shipper using the application/vnd.corp.manifest.v2+json content type.

Hint 6

The --data-binary @<file> option sends the content of a file as the request body, unchanged. The plain -d @<file> form strips newlines, which changes the bytes.

Note also that this endpoint requires the Content-Type of the manifest media type from the endpoint table, and the method has to be PUT.

Task 6: Delete a Resource

The cache-warmer artifact is no longer needed. Delete it. After the deletion, a GET for the artifact answers 410 Gone, because the server remembers that it existed.

Hint 7

A DELETE request has no body. A successful deletion answers 204 No Content, so curl prints nothing unless you add -i.

Tasks