tomjoht/learnapidoc

Repo for API doc book

This repo is now inactive. I moved the content into tomjoht.github.io repo, which surfaces the content at idratherbewriting.com.

The content is an API documentation course geared towards technical writers and engineers.

learnapidoc's Issues

Typo (literarily)

typo on this page:
https://idratherbewriting.com/learnapidoc/docapis_doc_sample_requests.html
literarily --> literally

Incorporate some of the research from The State of API report 2019 from Smartbear

The State of API Report 2019 from Smartbear has some amazing info re API trends that I should incorporate into the docs.

Missing '/' character on page: Step 2: Endpoints and methods (API reference tutorial)

Ther is a missing '/' character at resource URL on the page: Step 2: Endpoints and methods (API reference tutorial), see attached screenshot:

Create a Display Using Redoc -- Export does not provide a link

When I click on the export button in stoplight and select 'originail', I do not get a link. What happens is, a file "node.raw" is downloaded. "node.raw" is a yaml file.

Unix time format definition is not quite right )

URL: https://idratherbewriting.com/learnapidoc/docapis_new_endpoint_to_doc.html

In the "mock internal wiki page" Unix time epoch should be a number of seconds since 1970 (not milliseconds)

Minimal Typo in the "Documenting API endpoints" section

Hi Tom,

Great course you've got here. I thought I'd just point out a typo in the "Evaluate API reference docs" activity. Do find below a screenshot that shows the error in detail. Thanks!

H

https://idratherbewriting.com/learnapidoc/

Broken link in Activity: Use methods with curl

URL: https://idratherbewriting.com/learnapidoc/docapis_curl_with_petstore.html#get-your-pets-name-by-id

The JSON formatting site linked to (http://jsonprettyprint.com/) no longer exists. Perhaps you can use an alternative (http://jsonprettyprint.net/)?

Various comments on pages

Submitted from a reader:

---

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_understand_curl.html

QUESTIONS:

1. Under “Query strings and parameters”, would it be helpful to emphasize that the ampersand symbol separates, rather than concatenates, parameter-value pairs?

A description of the ampersand as a separator appears on the “Step 3: Parameters” page in Section III of your course, and such a description is consistent with RFC 6920, Section 3:

Query Parameters: A "tag=value" list of optional query parameters as are used with HTTP URLs [RFC2616] with a separator character '&' between each. For example, "foo=bar&baz=bat".

--> TJ: updated

---

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_curl_with_petstore.html

QUESTIONS:

1. In step 2 under “Create a new pet”, would “integer” be better than “integer (whole number)”?

Some readers might view “integer (whole number)” as a suggestion that integers and whole numbers are the same. Granted, an ID is unlikely to be negative, so an alternative to “integer” might be “integer (a whole number in this case)” or something similar.

--> TJ: updated

2. In step 5 under “Create a new pet”, would providing detail about idempotency for specific HTTP methods be helpful to the reader?

Including an abbreviated version of the table in RFC 7231, Section 8.1.3, might help clarify that the POST method is not considered idempotent:

Method Idempotent

GET yes
POST no
PUT yes
DELETE yes

(Please excuse the poor table formatting.)

--> TJ: updated. I believe I was incorrect in my content b/c I said that POST was indempotent here. I corrected that and expanded on the reference with the link you provided. Thanks!

---

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_access_json_values.html

NOTES:

1. In step 1 under “Printing a JSON value to the page”, the instructions appear to repeat the instructions in step 5 on the previous page (page title: “Inspect the JSON from the response payload”). That is, both steps ask the user to insert the following code below “console.log(response);”:

var content = response.wind.speed;
$("#windSpeed").append(content);

2. In step 2 under “Printing a JSON value to the page”, the reader is asked to insert a line so that the page body looks like this:

<body>
<h1>Sample page</h1>
<div id="windSpeed">Wind speed: </div>
</body>

However, the HTML provided in step 6 on the previous page already has the following:

<body>
<h1>Sample Page</h1>
wind speed: <span id="windSpeed"></span>
</body>

--> TJ: updated

3. In step 2 under “Printing a JSON value to the page”, the first HTML snippet includes a closing H2 tag rather than a closing H1 tag (<h1>Sample page</h2>).

--> TJ: updated

---

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_diving_into_dot_notation.html

QUESTIONS:

1. Would it be worth explaining why different variable-naming strategies are used in the code samples on the page (examples: “OpenWeatherMap”, “sarahjson”, “wind_speed”)?

--> TJ: this is just an inconsistency on my part. i don't have a strategy for using camelcase versus lowercase versus underscores. i will try to be more consistent, though. thanks for calling this out.

2. Under “Showing wind conditions on the page”, should the HTML example include the tag and the tag—to be consistent with the HTML example shown under “Exercise with dot notation”?

--> TJ: Updated. wow, you have a really careful eye here to catch all of this. I'm impressed by your meticulousness.

---

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_api_reference_tutorial_overview.html

NOTES:

1. Under “After the tutorial”, the gray note includes a link to Section IV, but the link text differs from the Section IV title; the link text is “OpenAPI specification and Swagger”, but the Section IV title is “OpenAPI spec and generated reference docs”.

--> TJ: Updated

---

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_doc_parameters.html

QUESTIONS:

1. Under “Max and min values for parameters”, would it be worth mentioning that allowed values need not be specified for boolean parameters because the boolean type already restricts values to true and false?

--> TJ: Updated

2. Under “Max and min values for parameters”, would it be worth mentioning that allowed values for string parameters can be specified using the enum type (to emphasize that values can be restricted in ways other than by specifying a max and/or min)?

-- TJ: Updated. good callouts here, by the way. these are valid use cases that I had totally omitted!

---

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_finished_doc_result.html

NOTES:

1. Under “Next steps”, the first activity link (“Activity: Find an Open Source Project”) takes the reader to the first activity in Section IX rather than the first activity in Section III.

--> TJ: I don't see this issue. Maybe I fixed it previously.

2. Under “Next steps”, the text for the second activity link (“Activity: Critique or create an API reference topic”) differs from the corresponding sidebar title (“Activity: Evaluate API reference docs for core elements”) and the activity page title (“Activity: Evaluate API reference docs”).

--> TJ: Updated

---

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_find_open_source_project.html

NOTES:

1. The title on the page is “Activity: Find an Open-Source Project”, whereas the corresponding sidebar title is “Activity: Find an Open Source Project” (that is, the title in the sidebar lacks a hyphen in the compound modifier; similarly for the link text at the bottom of the “Putting it all together” page in Section III).

--> TJ: Updated. I noticed I was inconsistent in other places in the course, so I updated those too.

Note also that the activity title appears in headline-style capitalization (both at the top of the activity page and in the sidebar), whereas the other page/section titles appear in sentence-style capitalization.

-- TJ: Updated

Instructions for exploring Aeris Weather API need to be updated

URL: https://idratherbewriting.com/learnapidoc/docapis_scenario_for_using_weather_api.html#aeris

The Weather API Endpoints webpage for AerisWeather now further classifies the endpoints into categories such as FEATURED, MOST POPULAR, SEVERE, etc, with MOST POPULAR being the default selection.

The observations endpoint can be found by clicking the ALL option (marked by the arrow) and scrolling through the list.

update list of parameter types

hello @tomjoht , i know this will require the rewrite of the whole docapis_doc_parameters.md page, which is why i didn't submit any edits there directly, but the new OpenAPI spec totally does away with the request body parameter (which was so nice and easy to understand in your writeup) and goes the object route with a parameter object vs. a requestBody object. it's still a wee bit hazy, but now the only types of params are header, path, query, and... drumroll <voice=CookieMonster>COOOOKIEEE...!!!.

so, yeah, would gladly lend a hand tweaking the text (or just helping edit/proofread), but i don't want to even begin suggesting how to handle the overhaul of that page. :)

love your work, keep coming back to your guides on the regular.

p.s.

sorry if i'm submitting this incorrectly, i'm a bit new here.

Replace Disqus with alternative comments service

The theme uses Disqus for comments. As described in multiple articles (e.g., Why you should remove Disqus from your site, Why I Replaced Disqus and You Should Too, and other articles), this service should be replaced with a less intrusive one (a service that doesn't inject a bunch of ad-tracking scripts onto the page).

Expand on the different types of APIs out there

Many people in the course get surprised when they go to GitHub to look for ways to contribute on API projects, or they look at the APIs at their work, and they get confused because they don't resemble the REST APIs covered in this course. I want to expand on the many different types of APIs out there.

Typo on page: Step 1: Resource description (API reference tutorial)

There is a typo on the page: https://idratherbewriting.com/learnapidoc/docapis_resource_descriptions.html

Confusing use of "zip" in sample SurfReport API request

URL: https://idratherbewriting.com/learnapidoc/docapis_finished_doc_result.html

In the example SurfReport API request in the Documenting API endpoints module, in keeping with the description of the path parameter, it would be preferable to replace zip with beachId to avoid confusion. (Also, a dummy beachID value could be used instead of an actual zip code?)

Postman import - OpenWeatherMap API collection - not working

Tried to import the collection OpenWeatherMap API collection in several methods, but was unable to import it.

Section - Automatically import the Postman collections

I have attached the screens to the steps I have done.
Import_Postman_Collection.pdf

Minor typo in text for Tip in Postman section

URL: https://idratherbewriting.com/learnapidoc/docapis_postman.html#-enter-several-requests-for-the-aeris-api-into-postman

I believe this should be API keys instead.

Link Issue

The "Next" link at the bottom of the "Create an OpenAPI specification document using Stoplight Studio's visual editor" page takes you to the "Activity: Create an OpenAPI specification document" section, skipping when I think the next section is supposed to be "Step-by-step OpenAPI tutorial".

Instructions to find the GET box and disabling SSL certificate verification can be added for first time Postman users

URL: https://idratherbewriting.com/learnapidoc/#testing-your-setup

To test Postman setup and help the first time users, you may consider adding a bit. For example, the description may be updated as follows-

If you want to test whether Postman works, open up the Postman app, go to Workspaces (on upper left corner of screen) > My Workspace, click the "+" icon and paste this into the GET box:
https://api.openweathermap.org/data/2.5/weather?zip=95050&units=imperial&appid=126cac1a482f51de0f1287b45ae2bf9a. Then click Send. If you get a response, it’s working correctly. (In rare cases, sometimes people have security restrictions on their computers that block all network access.)

Note
In case you do not get a response due to SSL certificate issues, go to Settings > General and toggle SSL certificate verification switch to OFF.

And lastly, your blog is extremely helpful and informative. Thanks for posting this great work and allowing the documentation community to grow.

Minor typo in text for What you'll need section

URL: https://idratherbewriting.com/learnapidoc/#what_you_need

This should be "as it works"

Add a "Note" to guide Windows users to access directory paths having spaces

Hi Tom,

Adding this observation since first time users may face the issue while using Command Prompt on Windows.

Issue Description: How a new user can access the Windows directory path if it contains multiple words separated by spaces? For example, Windows directory path can be something like this - "C:\Personal\API documentation"

Solution:
You may consider adding the following "Note" or text at the end of section Create a new pet > Step 4 > bullet point 2 ('On Windows, look at the prompt path to see your current directory. Then...')

If the Windows directory path contains multiple words separated by spaces, then keep the path within inverted commas ("..."). For example, type cd "<dir_path>" . For example, if you kept the JSON file in "C:\Personal\API documentation", then type cd "C:\Personal\API documentation".

Thanks!

Update Box developer documentation images

Hey Tom, firstly thank you so much for including my work on the Box site in your site. I was hoping to help you update some of the screenshots to reflect recent updates and clones this repo, but then realised I think this repo does not actually contain the images. Are these online somewhere where I can edit them?

Navigation instructions for exploring Aeris Weather API need to be updated

URL: https://idratherbewriting.com/learnapidoc/docapis_scenario_for_using_weather_api.html#aeris

The third step should read: "In the Weather Data API section, click Data Endpoints."