Databases
StackOverflow2013
Postsdbo
PO
 

Note that there are some explanatory texts on larger screens.

plurals
  1. PO
    primarykey
    data
    text
    <p>One of the reasons such a tool does not exist is because the documentation of a RESTful API should NOT include any of these items:</p> <ul> <li>Specify URLs/URIs format/structure</li> <li>Request/Response formats and methods (GET/POST/etc, XML/JSON/etc)</li> <li>Categorize endpoints/API Calls (such as grouping several calls under Authentication)</li> </ul> <p>RESTful API documentation is about documenting media types used and their associated application semantics. You should be looking to produce something that looks more like <a href="http://amundsen.com/hypermedia/profiles/" rel="nofollow">this</a>.</p> <p>The examples you have given are HTTP based RPC APIs which is why they require this type of endpoint documentation. They are RESTful in name only. Now, why people are not creating tools to automatically document HTTP based RPC APIs, I can't really tell you. Maybe it is because the people who are writing those APIs are so busy maintaining them that they don't have time to writing documentation tooling!</p>
    singulars
    1. This table or related slice is empty.
    1. POWhat is the best tool for documenting/generate reference for a RESTful/HTTP RPC API?
      singulars
      1. PTQuestion
    1. PTAnswer
    1. This table or related slice is empty.
    1. USDarrel Miller
    plurals
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. VO
      singulars
      1. PO
      1. This table or related slice is empty.
      1. VTUpMod
    2. VO
      singulars
      1. PO
      1. This table or related slice is empty.
      1. VTUpMod
    3. VO
      singulars
      1. PO
      1. This table or related slice is empty.
      1. VTUpMod
    1. COI understand you point, and I'm not looking to argue semantics, for exmaple http://en.wikipedia.org/wiki/Restful is pretty misleading on the subject. Personally I would distinguish a RESTful application and RESTful API as two different entities. However, in the interest of sanity, I will update my question to be more specific!
      singulars
      1. PO
      1. USColin
    2. CO-1: Dogmatic potshots over practicality. REST APIs need documentation too. Which HTTP status codes am I expected to receive for purposes of validation? How is authentication handled? Which character set am I supposed to use? What does the payload look like? Are any parts of it optional? What kind of data do individual components accept? You note that these things, as application semantics, are worth documenting, but you seem to deny that a tool that can be used to easily document this should exist, taking it instead to mean that the existence of a tool means you've picked the wrong solution.
      singulars
      1. PO
      1. USJesper
    3. CO@jesper Status code for the purpose of validation: 400. Authentication is handled however the www-authenticate header says it is. Either the media type or the link relation will tell you what the payload looks like. Charset? media type docs. Optional components, media type docs. If a tool can magically document it, then chances are you will end up with docs that say "GET /Customer to retrieve a Customer". Which IMHO is 100% redundant. In a RESTful system, discovery of resources should be dynamic, not in documentation.
      singulars
      1. PO
      1. USDarrel Miller
 

Querying!

 
Guidance
A row detail

Detail views are divided into sections. All the information in the data section comes from columns in the selected row. The other sections display data from other, related rows.

Related data can be related in a to-one or a to-many fashion. Captions of data related in a to-many fashion link to a list view showing a filtered view of the table.

Try moving around until you find a non-empty to-many entry and click on the label to get to one. You can move back to the root by clicking on the database name in the header.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload