Skip to main content

API

The Rock Paper Scissors API#

The Rock Paper Scissors API (RPSAPI) is a REST API that allows you to play rock paper scissors against a computer player. Using the RPSAPI, you can revisit a proven and universal method of dispute resolution from your childhood. You can use this API to build your own rock paper scissors front end for the game itself, or use the supplied documentation endpoints to generate an automated reference. This API is particularly useful for students and in teaching environments exploring REST APIs or practicing front end development.

Within the API, you can do the following:

  • Play a hand against the computer
  • Add and remove players
  • View a list of all players
  • View a player's scores
  • Update player names and delete players

Requirements#

To interact with the API and play Rock Paper Scissors, you need an http client that can send requests using the GET, PUT, POST, and DELETE methods, such as cURL. You also need an internet connection, but you do not need an account.

Getting started#

The most immediate way you can get started with rock paper scissors is to submit a request using form data. This button sends a form request to get all of the players:

The next-easiest way to submit requests, and the way this document provides all examples, is to use cURL. The following cURL command performs the same GET request as the form above:

curl -X GET http://techwriting.io/rpsapi/v1/players

Using cURL, you can manually call all of the endpoints in the Rock Paper Scissors API and play the game. See the Reference Section for all of the available endpoints and example cURL commands for each.

How it works#

The Rock Paper Scissors API codebase is Javascript, and it uses Express to handle requests and a Mongoose database to store player and game data.

The following diagram illustrates the general architecture of this API:

Diagram showing API traffic flow

  • Request A player makes an API request
  • Reverse Proxy The webserver routes traffic to the Express server
  • server.js Javascript code handles the request using the Express framework and Mongoose library
  • Response Responses are returned to the user

The following sections describe some of the more noteworthy details of how the API functions:

Computer hand generation#

The RPSAPI generates the computer's using a pseudorandom (in a generous sense of the term) algorithm based on the current time in seconds.

// use time for psuedorandom hand generation, take the modulus of 3 to select one of 3 hands              var notRandom = time.getSeconds() % 3;              <...>

Documentation endpoint#

RPSAPI documentation is written into the server.js source code, and you can access it at its own endpoint. The following code snippet shows the router get function, the endpoint string, and response JSON:

router.get('/v1/docs', function(req, res) {    res.json(      {        api_calls: [{          endpoint: '/',          data: {            method: 'GET',            parameters: 'NONE',            description: 'The root endpoint, returns connection info',            example: 'curl -X GET http://techwriting.io/rpsapi/v1/'          }        },        <...>

You can also explore a sample API documentation automation script, which automatically retrieves the reference documentation for this site from this endpoint, parses, and writes the data into this page's YAML frontmatter. For more information, including the full code, see the API Documentation Automation section of the Techwriting.io sample works page.

API versioning#

This API features rudimentary versioning support through manually prepended strings prepared for the router. You can use this to develop more sophisticated versioning code at a later date while not impacting the end user experience.

router.get('/v1/docs' <...>

Database#

A Mongoose library handles database access. The database itself is hosted by the Mlab cloud storage provider. This reduces the complexity of administration, and allows you to query the same database from both development and production versions of the API.

// open a connection with mongoose DB at mLab. This is not a production solution.mongoose.connect('mongodb://XXXXXX:yyyYYYyy@zzzZZZZz.mlab.com:55555/api', { useNewUrlParser: true });<...>

More information#

For more information, see the full Rock Paper Scissors API code in the Samples section.

API reference#

/

  • method: GET
  • parameters: NONE
  • description: The root endpoint, returns connection info
curl -X GET http://techwriting.io/rpsapi/v1/

/docs

  • method: GET
  • parameters: NONE
  • description: Returns this documentation
curl -X GET http://techwriting.io/rpsapi/v1/docs

/players

  • method: GET
  • parameters: NONE
  • description: Fetch a list of all players stored in the database.
curl -X GET http://techwriting.io/rpsapi/v1/players
  • method: POST
  • parameters: name (string)
  • description: create a new player
curl -X POST -d "name=Steve" http://techwriting.io/rpsapi/v1/players

/players/PLAYERID

  • method: GET
  • parameters: NONE
  • description: Fetch a specific player's name
curl -X GET http://techwriting.io/rpsapi/v1/players/5c5cc956608ab82cb789da6b
  • method: PUT
  • parameters: name (string), played (enumerated string: rock, paper, scissors)
  • description: Update a specific player's name or play a new hand. Use only one parameter at a time.
curl -X PUT -d "played=rock" http://techwriting.io/rpsapi/v1/players/5c5cc956608ab82cb789da6b
  • method: DELETE
  • parameters: NONE
  • description: Delete a specific player's name
curl -X DELETE http://techwriting.io/rpsapi/v1/players/5c5cc956608ab82cb789da6b