[Framers] OT-Documenting APIs

[Grant Hogarth]

Hi Shmuel
You are correct.  The second form are usually called REST or RESTful 
applications.
The main difference from our perspective is that for the REST type, you 
really do need to provide a lot more "recipes" for how the various HTTP 
requests (GET, POST, PATCH, DELETE, HEAD, OPTIONS, etc.) are used, and 
which requests are and are not supported.
This is because the same API will behave (and respond) differently 
depending on the type of request being made. A GET, for example, only 
returns information from the target, while a POST or PATCH will change 
the target.
A use case (highly recommended), should show how a user would make a 
request using a GET to retrieve information (for example, the name of 
the resource), and then use a PATCH to change the name.

For my own purposes, I define an "Example" as a single use of a command 
or call/request, and a "Use Case" as a collection of commands/calls that 
show how the user would achieve a desired task. By analogy, a Use Case 
is a routine that is composed of subroutines, while an Example would be 
a single-operation sub-routine.

Does this help?
Grant

------ Original Message ------
From: "Shmuel Wolfson" <shmuelw1 at gmail.com>
To: framers at lists.frameusers.com
Sent: 11/23/2017 3:59:55 AM
Subject: Re: [Framers] OT-Documenting APIs

>Just to add to what others have mentioned, I did a search for "API 
>documentation" on Udemy.com and there is a nice list of API courses:
>https://www.udemy.com/courses/search/?q=api%20documentation
>
>I think there are two different types of APIs:
>1. A list if software functions
>2. Web-based commands that allow you to interact with website 
>applications
>
>The two types seem very different. I write software reference manuals 
>that are like #1 above, but the API documentation examples here don't 
>look anything like what I write:
>https://github.com/PharkMillups/beautiful-docs
>
>Could someone verify if this is correct or not?
>
>--
>Shmuel Wolfson
>Technical Writer
>058-763-7133
>