Debrief - POST challenger 201

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.

Debrief Video

Patreon ad free version

POST /challenger (201)

Issue a POST request on the /challenger end 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

Debrief Notes

• 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
  • POST /challenger
  • use the X-CHALLENGER header 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.

Response

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)

Status Code

• 201 means 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-CHALLENGER
• LOCATION

Notes:

• X-CHALLENGER is 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
  • https://tools.ietf.org/html/rfc6648
  • “this is a matter for the designers of those protocols”

Notes: Location

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location
• 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

Reference Links

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST
• https://tools.ietf.org/html/rfc6648
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201
• https://httpstatuses.com/201
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405
• https://httpstatuses.com/405
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location

More Instructions And Download Links

Learn More and Start Testing