Search results

What's wrong with this topic answer key

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

This is the answer key for Activity: What’s wrong with this API reference topic.

After you’ve finished commenting on the Google Doc, go to this annotated Google doc.

Annotated Google doc showing answers

Alternatively, expand the answers below to see how many issues you found. If you found additional issues beyond those noted here, feel free to drop me an email letting me know. You can also add your own comments on the Google Doc answer key.

Answer key:

Resource description:

  • wordy. should be more concise and action-oriented
  • Surfreport probably shouldn’t capitalized

Endpoints and definition:

  • GET/POST should just be GET

  • no need for colon in {:beachId}

  • consider color coding {beachId}

Parameters:

  • Query string parameters are mixed into same table as Path parameters. Separate into different tables.

  • Where you get the beach ID isn’t specified

  • Number versus Integer is potentially inconsistent. Technically, a number refers to a float or double (which would allow for decimals), while an integer refers to a whole number. In this case, I doubt the beach IDs have decimals.

  • No default specified for time parameter

  • With time data types, why do some data types have examples but not all?

Sample request:

  • not in curl format

  • only one query string parameter shown; should include time too

  • zip query string parameter is included but not defined anywhere

  • appID includes long API key that should likely be shortened to a variable such as APIKEY

Sample response:

  • includes riptide element that isn’t defined in response definition

  • riptide missing comma after second instance

  • riptide not shown in third hour block

  • indentation formatting is a bit messed up with word riptide

Response definition:

  • wind description doesn’t indicate what measurement is used (knots?)

  • for wind, “int” should be spelled out as integer

  • watertemp doesn’t indicate measurement units either

  • surfheight data type is “Map” when it should be Integer

  • recommendation doesn’t include more detail such as how many possible recommendation strings are available, and what they even mean.

  • surfheight should either be surf_height or surfheight – response example conflicts with usage in response definition table

  • no hierarchy expressed for child elements (e.g., tide, wind, watertemp)

114% Complete

114/117 pages complete. Only 3 more pages to go.

Donate?

Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.