You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I gave this presentation to the WTD South Bay group. More details are [here](https://idratherbewriting.com/2018/01/19/wtd-south-bay-publish-api-documentation-presentation/). This video covers the [Publishing API docs](pubapis_overview.html) section in this course.
35
+
I gave this presentation to the WTD South Bay group. More details are [here](https://idratherbewriting.com/2018/01/19/wtd-south-bay-publish-api-documentation-presentation/). This video covers the [Publishing API docs](https://idratherbewriting.com/learnapidoc/pubapis_overview.html) section in this course.
I gave this presentation to the STC/WTD San Diego chapter. More details are [here](https://idratherbewriting.com/2018/02/14/openapi-and-swagger-presentation/). This video covers the [OpenAPI specification and Swagger](restapispecifications.html) section.
47
+
I gave this presentation to the STC/WTD San Diego chapter. More details are [here](https://idratherbewriting.com/2018/02/14/openapi-and-swagger-presentation/). This video covers the [OpenAPI specification and Swagger](https://idratherbewriting.com/learnapidoc/restapispecifications.html) section.
48
48
49
49
{% include random_ad4.html %}
50
50
51
51
### How to Add Swagger to your API
52
52
53
-
I gave this presentation as a TC Dojo webinar. More details are [here](https://idratherbewriting.com/2017/01/17/swagger-presentation-documenting-rest-apis/). It covers the [OpenAPI specification and Swagger](restapispecifications.html) section in this course.
53
+
I gave this presentation as a TC Dojo webinar. More details are [here](https://idratherbewriting.com/2017/01/17/swagger-presentation-documenting-rest-apis/). It covers the [OpenAPI specification and Swagger](https://idratherbewriting.com/learnapidoc/restapispecifications.html) section in this course.
Copy file name to clipboardExpand all lines: _docs/additional_resources/denver_workshop_recordings.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,7 +20,7 @@ These videos are from an API documentation workshop that I gave in Denver, Color
20
20
21
21
{% if site.format == "web" %}
22
22
23
-
{% include note.html content="For the most recent workshop recording, see the [Video recordings of API doc workshops](docapis_course_videos.html)." %}
23
+
{% include note.html content="For the most recent workshop recording, see the [Video recordings of API doc workshops](https://idratherbewriting.com/learnapidoc/docapis_course_videos.html)." %}
Copy file name to clipboardExpand all lines: _docs/additional_resources/docapis_aerisweather_example.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,7 +26,7 @@ In earlier tutorials, you integrated information from the [OpenWeatherMap API](h
26
26
27
27
## 1. Get the API keys
28
28
29
-
See the [Getting Started](http://www.aerisweather.com/support/docs/api/getting-started/) page for information on how to register and get API keys. (Get the free version of the keys available to development projects.) You will need both the ID and secret to make API calls. See [Get the Aeris Weather API secret and ID](docapis_get_auth_keys.html#aeris_weather_apikey) for more detail.
29
+
See the [Getting Started](http://www.aerisweather.com/support/docs/api/getting-started/) page for information on how to register and get API keys. (Get the free version of the keys available to development projects.) You will need both the ID and secret to make API calls. See [Get the Aeris Weather API secret and ID](https://idratherbewriting.com/learnapidoc/docapis_get_auth_keys.html#aeris_weather_apikey) for more detail.
Copy file name to clipboardExpand all lines: _docs/additional_resources/docapis_eventbrite_example.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -25,7 +25,7 @@ Eventbrite is an event management tool, and you can interact with it through an
25
25
26
26
## 1. Get an OAuth token
27
27
28
-
Eventbrite uses the [OAuth method for authorization](docapis_more_about_authorization.html#oauth). To make any kind of requests, you'll need an OAuth token, which you can learn about in [Eventbrite's Authentication docs](https://www.eventbrite.com/platform/api#/introduction/authentication).
28
+
Eventbrite uses the [OAuth method for authorization](https://idratherbewriting.com/learnapidoc/docapis_more_about_authorization.html#oauth). To make any kind of requests, you'll need an OAuth token, which you can learn about in [Eventbrite's Authentication docs](https://www.eventbrite.com/platform/api#/introduction/authentication).
29
29
30
30
{% include image_ad_right.html %}
31
31
@@ -45,7 +45,7 @@ To get event information, we'll use the [event](https://www.eventbrite.com/platf
45
45
46
46
Although Eventbrite explains how to pass the authorization into requests, it's easier to use the prebuilt curl from the documentation code samples, and then use Postman to convert it to JavaScript jQuery AJAX.
47
47
48
-
Eventbrite's documentation uses [Apiary](https://apiary.io/), which provides a try-it-out feature (or [API explorer](pubapis_design_patterns.html#interactive_api_explorers)) in the right pane. This pane opens up when you click **Retrieve an Event**:
48
+
Eventbrite's documentation uses [Apiary](https://apiary.io/), which provides a try-it-out feature (or [API explorer](https://idratherbewriting.com/learnapidoc/pubapis_design_patterns.html#interactive_api_explorers)) in the right pane. This pane opens up when you click **Retrieve an Event**:
49
49
50
50
<figure><ahref="https://www.eventbrite.com/platform/api#/reference/event/retrieve-an-event"class="noCrossRef"><imgsrc="{{site.media}}/eventsendpointeventbrite.png"alt="Retrieving an Eventbrite Event"class="large" /></a><figcaption>Retrieving an Eventbrite Event</figcaption></figure>
Open up [Postman](docapis_postman.html). In Postman, go to **File > Import** and then select the **Paste Raw Text** tab. Paste in the cURL code you copied.
80
+
Open up [Postman](https://idratherbewriting.com/learnapidoc/docapis_postman.html). In Postman, go to **File > Import** and then select the **Paste Raw Text** tab. Paste in the cURL code you copied.
81
81
82
82
{% include random_ad2.html %}
83
83
84
84
<figure><imgsrc="{{site.media}}/postmanpasterawtext.png"alt="Pasting curl into Postman"class="medium" /><figcaption>Pasting curl into Postman</figcaption></figure>
85
85
86
-
Then click **Import**. The information will populate in a new Postman tab. In Postman, if you expand the Headers tab, you will see the OAuth information. The GET box includes the Eventbrite retrieve endpoint with the event ID added as a [path parameter](docapis_doc_parameters.html#path_parameters).
86
+
Then click **Import**. The information will populate in a new Postman tab. In Postman, if you expand the Headers tab, you will see the OAuth information. The GET box includes the Eventbrite retrieve endpoint with the event ID added as a [path parameter](https://idratherbewriting.com/learnapidoc/docapis_doc_parameters.html#path_parameters).
87
87
88
88
In Postman, below the Send button, click **Code**. In the Generate Code Snippets dialog box, select **JavaScript > Jquery AJAX**. Copy the value shown:
The information returned from the event object has a lot more detail than we need. We just want to display the event's title and description on our site. We'll use the jQuery AJAX code copied from the earlier step to do this. Note that I won't go into full detail about this code. I covered this AJAX call in more detail in some earlier tutorials:
114
114
115
-
*[Inspect the JSON from the response payload](docapis_json_console.html)
116
-
*[Access and print a specific JSON value](docapis_access_json_values.html)
117
-
*[Dive into dot notation](docapis_diving_into_dot_notation.html)
115
+
*[Inspect the JSON from the response payload](https://idratherbewriting.com/learnapidoc/docapis_json_console.html)
116
+
*[Access and print a specific JSON value](https://idratherbewriting.com/learnapidoc/docapis_access_json_values.html)
117
+
*[Dive into dot notation](https://idratherbewriting.com/learnapidoc/docapis_diving_into_dot_notation.html)
118
118
119
119
To integrate the jQuery AJAX Postman code into your website and print the `title` and `description` fields in the response, use the following code:
Copy file name to clipboardExpand all lines: _docs/additional_resources/jeopardy_answer_key.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ last-modified: 2019-03-31
11
11
12
12
{% include image_ad_right.html %}
13
13
14
-
The API Jeopardy questions are in the [Conclusion section of Workshop Activities](workshop.html#conclusion).
14
+
The API Jeopardy questions are in the [Conclusion section of Workshop Activities](https://idratherbewriting.com/learnapidoc/workshop.html#conclusion).
15
15
16
16
{% if site.format == "print" %}
17
17
*Note: This content doesn't embed well in print because it contains JavaScript. Please go to [https://idratherbewriting.com/learnapidoc/jeopardy_answer_key.html] to view the content.*
Copy file name to clipboardExpand all lines: _docs/additional_resources/pubapis_api_blueprint.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ last-modified: 2019-12-29
11
11
12
12
Just as Swagger defines a spec for describing a REST API, [API Blueprint](https://apiblueprint.org/) is another specification for describing REST APIs. If you describe your API with this blueprint, tools that support API Blueprint can read and display the information.
13
13
14
-
Note that unless you're using a platform that specifically requires API Blueprint, I recommend using the [OpenAPI specification](pubapis_openapi_tutorial_overview.html) instead.
14
+
Note that unless you're using a platform that specifically requires API Blueprint, I recommend using the [OpenAPI specification](https://idratherbewriting.com/learnapidoc/pubapis_openapi_tutorial_overview.html) instead.
15
15
16
16
{% if site.format == "web" %}
17
17
* TOC
@@ -465,7 +465,7 @@ For this tutorial, we'll use a platform called Apiary to read and display the AP
465
465
```
466
466
467
467
{: .note}
468
-
If the code isn't easy to copy and paste, you can [view and download the file here](assets/files/apiblueprintweatherdata.md).
468
+
If the code isn't easy to copy and paste, you can [view and download the file here](https://idratherbewriting.com/learnapidoc/assets/files/apiblueprintweatherdata.md).
Copy file name to clipboardExpand all lines: _docs/additional_resources/pubapis_raml.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,9 +10,9 @@ path1: resources.html
10
10
last-modified: 2018-12-23
11
11
---
12
12
13
-
RAML stands for REST API Modeling Language and is similar to the [OpenAPI specification](pubapis_openapi_tutorial_overview.html). RAML is backed by [Mulesoft](https://www.mulesoft.com/), a full-service, end-to-end API company.
13
+
RAML stands for REST API Modeling Language and is similar to the [OpenAPI specification](https://idratherbewriting.com/learnapidoc/pubapis_openapi_tutorial_overview.html). RAML is backed by [Mulesoft](https://www.mulesoft.com/), a full-service, end-to-end API company.
14
14
15
-
Note that unless you're publishing your docs with Mulesoft or another platform that specifically requires RAML, I recommend using the [OpenAPI specification](pubapis_openapi_tutorial_overview.html) instead. However, Mulesoft offers enterprise-grade API design, management, and deployment capabilities. If you're using Mulesoft for your API, you probably want to use RAML for your documentation specification.
15
+
Note that unless you're publishing your docs with Mulesoft or another platform that specifically requires RAML, I recommend using the [OpenAPI specification](https://idratherbewriting.com/learnapidoc/pubapis_openapi_tutorial_overview.html) instead. However, Mulesoft offers enterprise-grade API design, management, and deployment capabilities. If you're using Mulesoft for your API, you probably want to use RAML for your documentation specification.
16
16
17
17
{% if site.format == "web" %}
18
18
* TOC
@@ -43,7 +43,7 @@ To understand the proper syntax and format for RAML, you need to read the [RAML
43
43
44
44
{% include random_ad3.html %}
45
45
46
-
Here's the OpenWeatherMap API (which we've been [using in this course](docapis_scenario_for_using_weather_api.html)) formatted in the RAML spec. (I actually just used [API Transformer](https://apimatic.io/transformer) to convert my OpenAPI 3.0 spec to RAML.) As you can see, RAML is highly similar to the OpenAPI spec.
46
+
Here's the OpenWeatherMap API (which we've been [using in this course](https://idratherbewriting.com/learnapidoc/docapis_scenario_for_using_weather_api.html)) formatted in the RAML spec. (I actually just used [API Transformer](https://apimatic.io/transformer) to convert my OpenAPI 3.0 spec to RAML.) As you can see, RAML is highly similar to the OpenAPI spec.
Copy file name to clipboardExpand all lines: _docs/additional_resources/whats_wrong_answer_key.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ last-modified: 2019-08-29
11
11
12
12
{% include image_ad_right.html %}
13
13
14
-
This is the answer key for [Activity: What's wrong with this API reference topic](docapis_api_whats_wrong_activity.html).
14
+
This is the answer key for [Activity: What's wrong with this API reference topic](https://idratherbewriting.com/learnapidoc/docapis_api_whats_wrong_activity.html).
15
15
16
16
After you've finished commenting on the Google Doc, go to this [annotated Google doc](https://docs.google.com/document/d/1ogj99YHhFMkXb-HMMMko-G9Hq9Rg6cztdT06-oUZm4E/edit).
Copy file name to clipboardExpand all lines: _docs/code_tutorials/docapis_code_difficulty.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,7 +13,7 @@ last-modified: 2021-10-08
13
13
Software code, often written in Java, C++, or any other language, is challenging to document in part because technical writers often aren't already fluent in the programming language. But even for writers or developers who are fluent in the language, code is hard to document. There isn't a step-by-step process to follow. Code is often arranged in non-linear order, so you can't simply proceed line-by-line through it. There's also the question of how much to document, what to cover, and where to include the documentation. Overall, best practices for documenting code are somewhat fuzzy and undefined, which makes documenting code one of the most challenging and difficult tasks technical writers face.
14
14
15
15
{: note}
16
-
In a previous topic, [Documenting code](docapis_codesamples_bestpractices.html), I briefly touched on the need to document code. But given the importance of this topic, I've expanded this section in more depth with its own dedicated topics here.
16
+
In a previous topic, [Documenting code](https://idratherbewriting.com/learnapidoc/docapis_codesamples_bestpractices.html), I briefly touched on the need to document code. But given the importance of this topic, I've expanded this section in more depth with its own dedicated topics here.
17
17
18
18
* TOC
19
19
{:toc}
@@ -115,4 +115,4 @@ Of course, the ideal is that you would also be comprehending what's going on in
115
115
116
116
## Next topic
117
117
118
-
Go on to the next topic in this series: [What research tells us about documenting code](docapiscode_research_on_documenting_code.html).
118
+
Go on to the next topic in this series: [What research tells us about documenting code](https://idratherbewriting.com/learnapidoc/docapiscode_research_on_documenting_code.html).
0 commit comments