API documentation overhaul by ocket8888 · Pull Request #3078 · apache/trafficcontrol

ocket8888 · 2018-12-03T17:13:53Z

What does this PR do?

This PR is an overhaul to the way the API documentation is laid out. It gives each unique request path its own page - but only considers request paths unique if they differ after the /api/1.x/ portion. Rather than a new page in every minor API version, the docs will use the versionchanged, versionadded, and deprecated reStructuredText directives to indicate changes between minor versions.
Also, each page follows the same, consistent formatting using proper section headings that allow links to specific parts of specific methods on an endpoint to be "link-able" - as well as the (now fully-HTTP wherever possible) request and response sections.
Grouping of endpoints by function is not currently implemented, but will probably be done when I finally get around to fixing up the index page with an explanation of the new layout.

Which TC components are affected by this PR?

What is the best way to verify this PR?

Build the documentation, and evaluate if the new layout is effective.

Check all that apply

This PR includes tests
This PR includes documentation updates
This PR includes an update to CHANGELOG.md
This PR includes all required license headers
This PR includes a database migration (ensure that migration sequence is correct)
This PR fixes a serious security flaw. Read more: www.apache.org/security

asfgit · 2018-12-03T17:19:06Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2863/
Test FAILed.

asfgit · 2018-12-03T18:08:15Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2864/
Test PASSed.

asfgit · 2018-12-04T20:15:43Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2879/
Test PASSed.

asfgit · 2018-12-04T23:02:42Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2880/
Test FAILed.

asfgit · 2018-12-04T23:33:34Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2881/
Test FAILed.

asfgit · 2018-12-05T01:51:55Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2882/
Test PASSed.

asfgit · 2018-12-05T17:43:56Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2885/
Test FAILed.

asfgit · 2018-12-05T22:11:23Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2894/
Test PASSed.

asfgit · 2018-12-06T02:36:40Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2898/
Test PASSed.

asfgit · 2018-12-07T22:16:01Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2919/
Test PASSed.

asfgit · 2018-12-10T15:39:38Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2920/
Test FAILed.

asfgit · 2018-12-10T15:48:56Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2921/
Test FAILed.

asfgit · 2018-12-10T18:53:24Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2922/
Test PASSed.

asfgit · 2018-12-10T19:01:12Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2923/
Test PASSed.

asfgit · 2018-12-10T20:47:04Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2925/
Test PASSed.

asfgit · 2018-12-11T14:51:08Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2929/
Test PASSed.

asfgit · 2018-12-11T17:21:16Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2931/
Test PASSed.

asfgit · 2018-12-11T21:56:18Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2936/
Test PASSed.

asfgit · 2018-12-12T16:52:04Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2938/
Test PASSed.

asfgit · 2018-12-12T22:59:24Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2940/
Test PASSed.

asfgit · 2018-12-13T00:01:19Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2941/
Test PASSed.

I may need to add more keys to the definition - CIAB has quite a few less than production environments, but I don't understand all of the nuances there

asfgit · 2018-12-13T23:34:15Z

Refer to this link for build results (access rights to CI server needed):
https://builds.apache.org/job/trafficcontrol-PR/2943/
Test PASSed.

mitchell852 added WIP "Work-in-Progress" - do not merge! (use 'draft' pull requests from now on) documentation related to documentation labels Dec 3, 2018

ocket8888 force-pushed the Even-more-documentation-updates branch 2 times, most recently from bcafca7 to f815175 Compare December 10, 2018 18:36

ocket8888 force-pushed the Even-more-documentation-updates branch from 92440e9 to e787e23 Compare December 11, 2018 14:45

ocket8888 force-pushed the Even-more-documentation-updates branch from e787e23 to 5693792 Compare December 11, 2018 17:13

ocket8888 force-pushed the Even-more-documentation-updates branch from 5693792 to 4238e01 Compare December 11, 2018 21:49

ocket8888 force-pushed the Even-more-documentation-updates branch from dfa8bd5 to 932ee5c Compare December 12, 2018 22:33

Moved API overview to the Index page

db94d73

ocket8888 added 22 commits December 13, 2018 16:10

fixed formatting error

5f33c80

Made minor improvements to deprecation formatting notice

1e03aa8

Added missing query parameter and added a deprecation notice

e9ec960

Fixed copy/paste typo

28ff6b8

Moved region endpoints into new structure

1a72605

Fixed a spelling error

bb226d2

Pulled v11/profile.rst and v12/profile.rst into new structure

76bd7d1

Pulled v12/profile_parameter into new structure

b3b1cfa

Moved v1x/role.rst into the new structure

a84ce54

Moved servers endpoints into new structure

3cd8d3c

Various syntax error fixes

327039b

Moved staticdnsentries endpoint into new structure

fdb168a

Moved statuses endpoints into new structure

a60fb15

Pulled steering endpoints into new structure

e1193e9

Moved last 1.3 endpoint (origins) into new structure

7d0f031

moved system info endpoint into new file structure

2e2be1e

I may need to add more keys to the definition - CIAB has quite a few less than production environments, but I don't understand all of the nuances there

Moved tenants endpoints into new structure

9d72f67

WIP - pulling to_extensions into new structure

a377ebe

Pulled Traffic Ops extensions endpoints into new structure

b34b3ea

Moved snapshot endpoints into new structure

2b30bb5

Moved types endpoints into new structure

58b96da

Pulled users endpoints into new structure

5006afa

ocket8888 force-pushed the Even-more-documentation-updates branch from 79814a8 to 5006afa Compare December 13, 2018 23:10

ocket8888 changed the title ~~WIP - API documentation overhaul~~ API documentation overhaul Dec 13, 2018

mitchell852 removed the WIP "Work-in-Progress" - do not merge! (use 'draft' pull requests from now on) label Dec 14, 2018

ocket8888 mentioned this pull request Dec 14, 2018

Fix typos #3124

Closed

17 tasks

dneuman64 merged commit 5bf0792 into apache:master Dec 14, 2018

ocket8888 deleted the Even-more-documentation-updates branch December 17, 2018 14:09

moltzaum mentioned this pull request Mar 8, 2019

Undocumented API Parameters #2726

Closed

Conversation

ocket8888 commented Dec 3, 2018

What does this PR do?

Which TC components are affected by this PR?

What is the best way to verify this PR?

Check all that apply

Uh oh!

asfgit commented Dec 3, 2018

Uh oh!

asfgit commented Dec 3, 2018

Uh oh!

asfgit commented Dec 4, 2018

Uh oh!

asfgit commented Dec 4, 2018

Uh oh!

asfgit commented Dec 4, 2018

Uh oh!

asfgit commented Dec 5, 2018

Uh oh!

asfgit commented Dec 5, 2018

Uh oh!

asfgit commented Dec 5, 2018

Uh oh!

asfgit commented Dec 6, 2018

Uh oh!

asfgit commented Dec 7, 2018

Uh oh!

asfgit commented Dec 10, 2018

Uh oh!

asfgit commented Dec 10, 2018

Uh oh!

asfgit commented Dec 10, 2018

Uh oh!

asfgit commented Dec 10, 2018

Uh oh!

asfgit commented Dec 10, 2018

Uh oh!

asfgit commented Dec 11, 2018

Uh oh!

asfgit commented Dec 11, 2018

Uh oh!

asfgit commented Dec 11, 2018

Uh oh!

asfgit commented Dec 12, 2018

Uh oh!

asfgit commented Dec 12, 2018

Uh oh!

asfgit commented Dec 13, 2018

Uh oh!

asfgit commented Dec 13, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants