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
- wget is here and curl is not; both send one request, and the choice is what the machine has.
- HttpClient from a C# program is the client of the previous lesson, and it also sets a base address and a timeout.
- A Python service uses urllib.request from the standard library, or a package for retries and sessions, which this container would have to install.
- Every client sets a timeout: a server that stops answering must not block the caller for ever, and a retry with a bound is the next step after it.
Exercises
- Send a POST with wget --post-data and the JSON content type, and read the 201.
- Request an id that is not a number and see the 404 of the route constraint.
- Add a timeout to urlopen and call a port that nothing listens on.
- 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.
-
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.
-
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.
-
What does the status attribute of the response hold?
Answer
200
The measured line printed status 200.
-
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.
-
What does json.loads do?
Answer
Turns JSON text into Python values
The body became a dictionary, which the print showed.
-
Which header names the format of the body?
Answer
Content-Type
The response carried application/json; charset=utf-8.
-
What does the Server header name?
Answer
The server software, Kestrel here
The measured header was Server: Kestrel.
-
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.
-
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.
-
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