Calling the API

An HTTP API is called by anything that speaks HTTP, and the language of the caller is a detail. The server of the previous lesson listens on http://127.0.0.1:5080 with one route, and this lesson calls it with the tools of this container. The calls and their output are from a real run against that server; curl is not installed here, so the shell tool is wget.

The server that was called

The program is the one of the previous lesson with the client part removed and a final app.Run(), which keeps the server listening until the process is stopped:

It is the program of lesson 097 with the client part removed: the builder, UseUrls("http://127.0.0.1:5080"), the two routes, and a final app.Run() that keeps the server listening until the process is stopped. Started with dotnet run, it prints its first line and stays in Run, which is why a client is the only way to see what it does. The project file is the one of the previous lesson, with the framework reference to Microsoft.AspNetCore.App.

The line printed and the program stayed in app.Run(), which does not return until the process is stopped. The project file is the one of the previous lesson, with the framework reference to Microsoft.AspNetCore.App.

wget from the shell

wget -q -O - sends a GET and writes the body to the standard output, which is the shortest probe of a route:

wget -q -O - http://127.0.0.1:5080/orders/42

{"id":42,"total":63.0}

The status line, the content type and the server name are in the response headers, which -S shows while the body goes to /dev/null:

wget -S -q -O /dev/null http://127.0.0.1:5080/orders/42 2>&1 | grep -E 'HTTP|Content-Type|Server'

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
  Server: Kestrel

Kestrel names itself in the header, and the content type is the one Results.Json sets. A route that does not exist answers 404, which wget reports as a failed download with a status of 8, not as the number 404: the status is in the header, and the exit status of the tool is its own convention.

urllib from Python

A client in a program reads the status, the headers and the body as separate things. The script below uses only the standard library:

import json import urllib.error import urllib.request with urllib.request.urlopen("http://127.0.0.1:5080/orders/42") as response: print("status", response.status) print("type", response.headers["Content-Type"]) print(json.loads(response.read())) try: urllib.request.urlopen("http://127.0.0.1:5080/nothing") except urllib.error.HTTPError as error: print("missing", error.code)

python3 client.py

status 200
type application/json; charset=utf-8
{'id': 42, 'total': 63.0}
missing 404

The body arrived as bytes, json.loads turned it into a dictionary, and the missing route raised HTTPError instead of returning a response, because urlopen treats a status of 400 or above as an error. A client that wants the body of a 404 catches the exception and reads error.read(), which is where an API puts its problem details.

Which client to use

Exercises

  1. Send a POST with wget --post-data and the JSON content type, and read the 201.
  2. Request an id that is not a number and see the 404 of the route constraint.
  3. Add a timeout to urlopen and call a port that nothing listens on.
  4. Print every response header of the first request from the Python script.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Which tool in this container sends an HTTP request from the shell?

    Answer

    wget

    curl is not installed here and wget is, which the measured commands show.

  2. What does urllib.request.urlopen return for a 200 response?

    Answer

    A response object with status, headers and a body

    The script read response.status, the headers and the body from it.

  3. What does the status attribute of the response hold?

    Answer

    200

    The measured line printed status 200.

  4. Which exception does urlopen raise for a 404?

    Answer

    urllib.error.HTTPError

    A status of 400 or above is an error for urlopen, as the missing route showed.

  5. What does json.loads do?

    Answer

    Turns JSON text into Python values

    The body became a dictionary, which the print showed.

  6. Which header names the format of the body?

    Answer

    Content-Type

    The response carried application/json; charset=utf-8.

  7. What does the Server header name?

    Answer

    The server software, Kestrel here

    The measured header was Server: Kestrel.

  8. Why does a client pass a timeout to urlopen?

    Answer

    A server that stops answering must not block it for ever

    Without one the call waits as long as the operating system allows.

  9. Which address must the app listen on to be reachable outside its container?

    Answer

    http://0.0.0.0:8080

    A loopback address accepts only connections from the same machine.

  10. Does a client have to be written in C#?

    Answer

    No, HTTP and JSON are the contract

    The measured client was Python, and wget called the same route.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev