[Geoserver-devel] [JIRA] (GEOS-7931) Improved REST API Documentation

GeoServer GeoServer Developer
1

Torben Barsballe created an issue

GeoServer / ImprovementGEOS-7931

Improved REST API Documentation

Issue Type:

ImprovementImprovement

Assignee:

Unassigned

Components:

Documentation, REST

Created:

17/Jan/17 1:29 AM

Priority:

MediumMedium

Reporter:

Torben Barsballe

The REST API documentation has been a fairly consistent cause for complaint among GeoServer users, and would benefit from a considerable revamp.

Looking at the 70+ REST API tickets , doc fixes may close a large portion of them, as many of those are due to documentation confusion.

The MapBox REST API provides a good template with info / curl example / request / response.

Compare:

Approach:

  • Review the REST API tickets (above) and prioritize what to focus on for rest api docs.
  • Refactor current REST API content into a more approachable presentation, with API structure documentation followed by specific examples.

Design:
Document Each REST Endpoint (Syntax, supported request types/ response types/codes). Follow up with one or more relevant examples, such that examples and documentation for any given endpoint is in the same place.
For appearance, aim towards more of a field-list kind of presentation, so not side by side like the mapbox page.

We will have to decide what to do with the more complex examples that use several different endpoints. They can probably remain in a dedicated examples section.

Nice-to-haves:

  • Examples for gsconfig(python) and geoservermanager (java)
    but see above, try and present what we already have better…
  • Sliders for switching response types (HTML vs JSON). (Something similar has been considered for the SLD cookbook - switching between SLD and CSS).

Add Comment

Add Comment

This message was sent by Atlassian JIRA (v1000.695.1#100025-sha1:c4480eb)

Atlassian logo