Docs

Table of Contents

1. Challenge Server API Reference
2. Front Matter Reference
3. Usage in Slack
4. Usage in Github Actions
5. Usage in Github PRs

Challenge Server API Reference

The FizzBuzz cli creates a challenge server that provides endpoints:

• for applicants to request to start a challenge
• to render your markdown file
• for applicants to submit questions about a challenge
• for applicants to submit their solutions

POST api/challenges/<id>/applications

Request to start a challenge.

Request body:

{
  "email": "string"
}

Response body:

{
  "cookie": "fbmd_token=<token>",
  "challengeUrl": "https://makefizz.buzz/challenges/<id>",
  "docs": "https://makefizz.buzz/docs#get-challenge"
}

GET /challenges/<id>

Set the token received from the POST /<id>/applications endpoint as a cookie value via browser dev tools to render your challenge.

The clock starts against timeLimitHours as soon as this endpoint is called.

POST api/challenges/<id>/queries

Pass the token received from the POST /<id>/applications endpoint in an Authorization header to submit questions about the challenge.

Authorization: Bearer <token>

Request body:

{
  "query": "string"
}

The query will be sent to the support email address set in the front matter. Replies will be sent to the email sent in the POST /<id>/applications request.

POST api/challenges/<id>/submissions

Pass the token received from the POST /<id>/applications endpoint in an Authorization header to submit your solution.

Request body:

{
  "solutionLink": "string"
}

Front Matter Reference

# Email address that will receive messages when applicants submit questions 
# about the challenge via a POST to /api/<id>/queries
supportEmail: "support@fizzbuzz.md"

# Email address that will receive submissions via a POST to api/<id>/submissions
submissionEmail: "submission@fizzbuzz.md"

# Number of hours applicants have to submit their solution. Late submissions are flagged.
timeLimitHours: 72

# Whether the challenge is viewable w/o a session token generated from a POST request
public: true

# Email address that will receive rejection emails
rejectionEmail: >
  Thanks for applying. Unfortunately, we've decided to move forward with other candidates.

# Email address that will receive acceptance emails
acceptanceEmail: >
  Congratulations! We're moving forward with your application. Please book a time with this link: calendly.com/forward

# Company name that will be used in the submission email response
companyName: "FizzBuzz.md"

Usage in Slack

An easy way to set up a challenge so that multiple team members can respond to queries and solutions is to use Slack's email integration feature. If you create separate channels for queries and solutions (e.g., #challenge-queries and challenge-submissions), you can have separate emails for the supportEmail and submissionEmail front matter fields.

Usage in Github Actions

If you'd like to update your challenge file in a Github Actions workflow, you can use download the fizzbuzz.md cli and use it easily in a github action:

steps:
  - name: Update challenge file
    env: 
      FBMD_TOKEN: ${{ secrets.FBMD_TOKEN }}
      FBMD_EMAIL: ${{ secrets.FBMD_EMAIL }}
    # npx is intaled by default on runners
    # https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/
    run: npx zx https://makefizz.buzz/cli <Challenge-File>

Usage in Github PRs

Reviewing challenges is recommended. Apparently, Github lets you review rich renderings of markdown files in PRs: