API project creation

[buhman]

I noticed the v2 api appears completely undocumented. There's a reference to Django Rest Framework from api.html, which only appears to be able to describe the Api Root.

For example, if I specifically request project api documentation using http://readthedocs.org/api/v2/project/?format=api, I get a {"detail":"Not found"} response.

---

After reading the source, it doesn't look like there are any view methods for creating projects anyway.

Is this considered a generally (un)desirable feature, or has it just not been implemented?

[willingc]

The v2 api is documented here. Additional documentation is here (though this covers v1 and is out of date).

[buhman]

The v2 api is documented here.

Not really? Like I mentioned, that page just mentions root resources, but links to the resource documentation just return raw API responses instead of documentation. https://readthedocs.org/api/v2/project/

[potasiak]

I would like to be able to create projects through API and simple answer whether it will or won't be implemented would be very nice.

Also I can confirm that the self-documentation for API v2 does not work beyond the Api Root.

I have tried to send POST request to /api/v2/project/ endpoint and got:

{"repo":["This field is required."],"slug":["This field is required."],"users":["This list may not be empty."],"name":["This field is required."]}

Adding those parameters in JSON payload does not help - I got the exact same response. Same for passing those parameters in URI (GET fields).

[jaraco]

I was able to successfully create a project thus:

$ curl https://readthedocs.org/api/v2/project/ -X POST -H "Content-Type: application/json" -d '{"repo": "https://github.com/jaraco/jaraco.collections.git", "slug": "jaracocollections", "name": "jaraco.collections", "users": [744]}' -u "jaraco:$(keyring get readthedocs jaraco)"
{"id":141340,"name":"jaraco.collections","slug":"jaracocollections","description":"","language":"en","repo":"https://github.com/jaraco/jaraco.collections.git","repo_type":"git","default_version":"latest","default_branch":null,"documentation_type":"sphinx","users":[744],"canonical_url":"http://jaracocollections.readthedocs.io/en/latest/"}

One issue was that I had to know my user ID. To find my user ID, I cycled through https://readthedocs.org/api/v2/project/?limit=999 until I found a project for which I'm the sole user (somewhere around 26000). Best I can tell, the project API doesn't offer any way to search or filter, so the only option is to search all. Additionally, I don't think there's an API for the user records.

But alas, even after successfully creating the repo, it hasn't configured the web hook to Github, so the project doesn't get built without manually setting up the webhook. Best I can tell, there's no API to create the webhook, no way to tell what the webhook is for a project, and one would still need to install that webhook into Github manually for it to work.

Can anyone help with:

• how to resolve one's user ID?
• how to configure a webhook through the API (and retrieve the resultant URL)?

With those two things, I believe I could build a routine that could through the RTD API and the Github API, register a project and configure the web hook.

[scottnasello]

@jaraco - we are running RTD locally and this method is creating a manual webhook for us:

curl http://rtd.ourdomain.com/api/v2/project/ -X POST -H "Content-Type: application/json" -d '{"repo": "http://yourtokenhere:x-oauth-basic@read_the_docs_test.git", "slug": "NewProjectName2", "name": "NewProjectName2", "users": [2]}' -u

[jaraco]

Hi @scottnasello Thanks for the suggestion. I'm afraid it doesn't seem to suggest anything differently from what I'm doing above... which works to create the project in RTD, but it doesn't register a webhook within Github (where the repo exists) to signal when a commit is made so the docs can be rebuilt. In fact, your 'repo' URL doesn't look like a valid URL at all. It indicates a token, password, and maybe a path... or maybe a hostname ending in .git... I can't really tell.

Are you saying that after you issue a command like that to your local RTD instance that your docs get built when you push a commit?

[jaraco]

I've added a bounty to this issue in the hopes of incentivizing its completion. The API should present the same functionality as the "Import Project" UI does, including automatic user ID resolution and installation of the relevant Github webhook.

[AdiL2608]

I wrote a Python script to set up a project on my local instance of a read-the-docs server. My server is configured for http.
The calls are made via http GET and POST and I used Wireshark to emulate the project creation when using the webinterface.
You can view the code here: https://gist.github.com/AdiL2608/344e4149681ead0f2a5193ea6b15492b

[jaraco]

Thanks @AdiL2608 . I think your technique gets us closer. It definitely answers the second question - how to generate the webhook URL to be installed with GitHub. It unfortunately doesn't answer the question, how does one resolve the user's ID. As you can see in this line, the user ID is hard-coded... so that script will only work when the user's ID is 2.

If you can devise a technique for resolving the user's ID, then I should be able to put all these pieces together into a routine that installs a new project end-to-end.

[stsewd]

@jaraco you can get that information from this endpoint https://readthedocs.org/api/v1/user/?username=stsewd. And btw we are planning our v3 API #4286 (but it will read-only too)

[jaraco]

Thanks to everybody for putting together the pieces. Looks like by cobbling together the v1 api, v2 api, the RTD form API, and the GitHub API, I was able to create a script that creates a RTD project from a GitHub checkout. I've pushed the script to my repo as 6ad05b1.

I'll send a PR to see the functionality published/maintained in the repo (although not included as part of the distribution).

[stsewd]

I thinking about moving this request to #4286, that sounds good?

[jaraco]

Yes. Works for me (to shift focus to v3 API).

[stsewd]

Ok, moved to #4286 (comment)