Add documentation for APIv2

[davidfischer]

• 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.

[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.

[ericholscher]

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)

[davidfischer]

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?

[davidfischer]

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.

[davidfischer]

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

Sounds good

[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 :)

[RichardLitt]

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]

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]

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 :)