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" <shmue...@gmail.com>
To: framers@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
_______________________________________________
This message is from the Framers mailing list
Send messages to framers@lists.frameusers.com
Visit the list's homepage at http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com
