This post and video discusses what we can learn from the challenge
POST /challenger 201.
What are the API Challenges?
Our API Challenges Application has a fully functional cloud hosted API, and a set of challenges to work through.
If you haven’t yet completed the Challenge in API Challenges. Then is is worth trying. Find details on how to use the Challenges APP at /apichallenges or how to complete this challenge in this overview post.
POST /challenger (201)
Issue a POST request on the
/challengerend point, with no body, to create a new challenger session. Use the generated X-CHALLENGER header in future requests to track challenge completion.
- This challenge is essential if you want to persist your sessions in multi-user mode
- This challenge is optional if you want to work in single-user mode
- Normally we start learning with a GET,
- but to track challenges we are forced to start with POST
- APIs are not always intuitive
- they are designed for ‘programs’, ‘systems’, or ‘applications’ to interact with, not necessarily people
- The Challenge
- use the
X-CHALLENGERheader in all future requests.
What does this do? Why is this a POST?
POST /challenger HTTP/1.1 Host: localhost:4567 User-Agent: insomnia/6.5.4 Accept: */* Content-Length: 0
If I was describing this to a person, I might say:
- “I need the system to give me an X-CHALLENGER code, so that I can track my challenge session”
- “I need to get an X-CHALLENGER code to track my challenges”
What we are actually saying to the system is:
- “I need you to create a challenger session, and tell me what it is”
We are asking the system to make a change on the server side, in response to this request.
We use a
POST request to do that.
If I used a
GET request, and the system created a
challenger session in response then that is not in the spirit of the HTTP specification.
GET should be cacheable, and return information, not create information as a side-effect.
POST is used to create information on the server.
HTTP/1.1 201 Created Date: Tue, 28 Jul 2020 14:26:48 GMT X-CHALLENGER: rest-api-challenges-single-player Location: /gui/challenges Content-Type: text/html;charset=utf-8 Transfer-Encoding: chunked Server: Jetty(9.4.z-SNAPSHOT)
201means it created an entity or ‘something’ in the system
- What other status codes could be provided?
- API documentation doesn’t say
- Assume: 405
What are the headers in the response?
The response has two important headers for us.
X-CHALLENGERis a custom header.
- applications are free to create custom headers
X-...used to be the standard recommended approach
- Based on this ‘standard’ it is now a deprecated recommendation, but still used
- “this is a matter for the designers of those protocols”
- used with 303 and 201
- if a browser then it will follow Location header
- semantics are ‘looser’ for APIs
- here it tells us that we can see the created entity in the GUI