Repository: readthedocs/readthedocs.org

Issue:
Provide an API to query the build status by commit
In order to do a check before release that everything is ok, I would like to have a way to obtain the current build status for a given commit. So, in addition to:

```
GET /api/v1/build/{id}/
```

also have this:

```
GET /api/v1/commit/{sha1}/
```

or 

```
GET /api/v1/{user}/{project}/commit/{sha1}/
```

Is this possible right now?



Discussion:
Neat. We currently don't record the commit hash for builds. This is a good idea, and would allow that kind of API.

Any news on this? Any way I can help?

New (simpler?) idea: Is it possible to insert the commit hash in the sphinx html? If it can be done already, then I just need to download the the page and check that it matches the version my latest hash.

This should be part of newly built documentation with our theme already, we pass the commit hash in with via the API. We are storing the commit hash on the build object now, but we don't expose the commit as a first class endpoint in the api.

You can find similar API endpoints here: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/restapi/views/core_views.py

Adding a `build_status` endpoint to that file with a test would be a good place to start. 

This looks like it might have some overlap with #2251 which also adds commit ids to builds.
@agjohnson This "good first issue" is quite old. Can we improve the solution to fixing it, to encourage contribution? Same with https://github.com/rtfd/readthedocs.org/issues/1045. 
Would it be possible to get a more up to date information on this issue? I'm interested to have a look. Thanks.
> Would it be possible to get a more up to date information on this issue? I'm interested to have a look.

Thanks for your interest.

I think the original aspect of the issue is still valid: "build an API endpoint that receive a project and a commit hash and return the status (failed/success) of that build"

The `Build` object should have the commit hash: https://github.com/rtfd/readthedocs.org/blob/1af444173481df9a7b16e015fc6b12abe8155e7e/readthedocs/builds/models.py#L430-L431

So, I think we have all the information to create that endpoint. This could be next to the others at this file: https://github.com/rtfd/readthedocs.org/blob/1af444173481df9a7b16e015fc6b12abe8155e7e/readthedocs/restapi/views/model_views.py

@Alig1493 let me know if you are able to start with that info or not. Please, keep us updated on this :)

Thanks!
Will the api endpoint be under v1 or v2?
v2 is the right place.
v1 is deprecated and shouldn't be used.
@humitos There are already `api/v2/buid/<id>`, so what should be the endpoint for this?
Yes. What I understood from the original report is to have the ability that given the sha and the project you can know the status of that build.

Now, a build id is needed, that you don't know how to get it from a sha.

Makes sense?
@humitos I have understand. I wanted to explain that, there are already a endpoint for `api/v2/buid/<id>`, so the getting with another endpoint like `api/v2/buid/<commit hash>` will make the user confuse.
So I was wondering, what the API endpoint will look like. Can you please clarify?

Resolving patch:
diff --git a/readthedocs/restapi/views/model_views.py b/readthedocs/restapi/views/model_views.py
--- a/readthedocs/restapi/views/model_views.py
+++ b/readthedocs/restapi/views/model_views.py
@@ -243,7 +243,7 @@ class BuildViewSetBase(UserSelectViewSet):
     serializer_class = BuildSerializer
     admin_serializer_class = BuildAdminSerializer
     model = Build
-    filter_fields = ('project__slug',)
+    filter_fields = ('project__slug', 'commit')
 
 
 class BuildViewSet(SettingsOverrideObject):


Test patch:
diff --git a/readthedocs/rtd_tests/tests/test_api.py b/readthedocs/rtd_tests/tests/test_api.py
--- a/readthedocs/rtd_tests/tests/test_api.py
+++ b/readthedocs/rtd_tests/tests/test_api.py
@@ -414,6 +414,22 @@ def test_get_invalid_raw_log(self):
         resp = client.get('/api/v2/build/{0}.txt'.format(404))
         self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
 
+    def test_build_filter_by_commit(self):
+        """
+        Create a build with commit
+        Should return the list of builds according to the
+        commit query params
+        """
+        get(Build, project_id=1, version_id=1, builder='foo', commit='test')
+        get(Build, project_id=2, version_id=1, builder='foo', commit='other')
+        client = APIClient()
+        api_user = get(User, staff=False, password='test')
+        client.force_authenticate(user=api_user)
+        resp = client.get('/api/v2/build/', {'commit': 'test'}, format='json')
+        self.assertEqual(resp.status_code, 200)
+        build = resp.data
+        self.assertEqual(len(build['results']), 1)
+
 
 class APITests(TestCase):
     fixtures = ['eric.json', 'test_data.json']