New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for APIv2 #4274

Merged
merged 5 commits into from Jun 21, 2018

Conversation

Projects
None yet
4 participants
@davidfischer
Contributor

davidfischer commented Jun 19, 2018

  • This is a pure docs PR. There are no code changes.
  • Move internal class API (classes, functions, autodoc stuff) to developer-interface/ folder in the docs.
  • Move APIv1 docs into a folder and add APIv2 along side it
  • Deprecate insecure HTTP access to the API for removal in Jan 2019
  • Deprecate with no firm timeline APIv1
  • Mention API v3 development

Fixes #1175

Note

After merging, we should add a redirect from /api.html -> /api/v1.html.

Add documentation for APIv2
- This is a pure docs PR, no code changes
- Move internal class API to "developer-interface" folder
- Move APIv1 into a folder and add APIv2

@davidfischer davidfischer requested a review from rtfd/core Jun 19, 2018

@ericholscher

I think instead of moving the developer API, we should probably remove it for now. I don't believe it's being heavily used, and moving it will mean we just need to move it again once we rebuild it properly. It doesn't even document half the code currently, so I think having it there and half complete is worse than not there at all.

Largely this endpoint should be used only to get the Project ID
which is used in other API calls.
.. http:get:: /api/v2/search/project/?q={query}

This comment has been minimized.

@ericholscher

ericholscher Jun 20, 2018

Member

I'm not sure we should document this. It's not meant to be a public API, and it will be changing in our search upgrade GSOC project (#4265)

This comment has been minimized.

@davidfischer

davidfischer Jun 20, 2018

Contributor

If there's no way to get the project ID in APIv2 then the API can't really be used for projects. Is there a better way?

This comment has been minimized.

@davidfischer

davidfischer Jun 20, 2018

Contributor

I think what I'll do is just remove this call. Perhaps a nice addition (in another PR) would be to add filtering that would allow searching based on a few fields (notably ?slug=) so people can get the ID of their project.

@ericholscher ericholscher requested a review from rtfd/core Jun 20, 2018

@davidfischer

This comment has been minimized.

Contributor

davidfischer commented Jun 20, 2018

I think instead of moving the developer API, we should probably remove it for now.

Sounds good

davidfischer added some commits Jun 20, 2018

@ericholscher

Looks good. I'm curious if we'll get any pushback around removing the API docs, if so that's good signaling that we should create better ones. I'd much prefer to spend the time writing words documenting the actual code instead, but that's much harder :)

@ericholscher ericholscher merged commit 048acd1 into master Jun 21, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@RichardLitt

This comment has been minimized.

Member

RichardLitt commented Jun 21, 2018

Looks good. I'm curious if we'll get any pushback around removing the API docs, if so that's good signaling that we should create better ones. I'd much prefer to spend the time writing words documenting the actual code instead, but that's much harder :)

I wonder if we should open an issue to capture latent pushback. We don't know what people don't complain about, and leaving a space for that may help us capture sentiment better.

@ericholscher

This comment has been minimized.

Member

ericholscher commented Jun 21, 2018

I wonder if we should open an issue to capture latent pushback. We don't know what people don't complain about, and leaving a space for that may help us capture sentiment better.

@RichardLitt Makes sense. I'll open one.

@davidfischer

This comment has been minimized.

Contributor

davidfischer commented Jun 21, 2018

After merging, we should add a redirect from /api.html -> /api/v1.html.

I created this redirect

@humitos

This is already merged but I want to say that I loved your work :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment