Skip to content
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
Merged

Add documentation for APIv2 #4274

merged 5 commits into from Jun 21, 2018

Conversation

@davidfischer
Copy link
Contributor

@davidfischer 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.

- 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 Jun 19, 2018
Copy link
Member

@ericholscher ericholscher left a comment

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.

docs/api/v2.rst Outdated
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}
Copy link
Member

@ericholscher ericholscher Jun 20, 2018

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)

Copy link
Contributor Author

@davidfischer davidfischer Jun 20, 2018

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?

Copy link
Contributor Author

@davidfischer davidfischer Jun 20, 2018

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 Jun 20, 2018
@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Jun 20, 2018

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

Sounds good

Copy link
Member

@ericholscher ericholscher left a comment

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
@RichardLitt
Copy link
Member

@RichardLitt 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
Copy link
Member

@ericholscher 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
Copy link
Contributor Author

@davidfischer davidfischer commented Jun 21, 2018

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

I created this redirect

Copy link
Member

@humitos humitos left a comment

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
Labels
None yet
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

4 participants