Ship API v3

docs/api/index.rst

@@ -11,3 +11,4 @@ from Read the Docs.
     :maxdepth: 3
 
     v2
+    v3

docs/api/v2.rst

@@ -1,22 +1,22 @@
-API v2
-======
+API v2 (deprecated)
+===================
 
 The Read the Docs API uses :abbr:`REST (Representational State Transfer)`.
 JSON is returned by all API responses including errors
 and HTTP response status codes are to designate success and failure.
 
 .. note::
 
-    A newer API v3 is in early development stages.
+    A newer and better API v3 is ready to use.
     Some improvements coming in v3 are:
 
-    * Search API
-    * Write access
-    * Simpler URLs which use slugs instead of numeric IDs
+    * Simpler URLs which use slugs
+    * Token based authentication
+    * Import a new project
+    * Activate a version
     * Improved error reporting
 
-    If there are features you would like in v3, please get in touch
-    in the `issue tracker <https://github.com/readthedocs/readthedocs.org/issues>`_.
+    See its full documentation at :doc:`/api/v3`.
 
 
 Authentication and authorization

docs/api/v3.rst

@@ -1,23 +1,10 @@
-:orphan:
-
 API v3
 ======
 
 The Read the Docs API uses :abbr:`REST (Representational State Transfer)`.
 JSON is returned by all API responses including errors
 and HTTP response status codes are to designate success and failure.
 
-.. warning::
-
-   APIv3 is currently under development and it's not ready to use yet.
-
-
-.. note::
-
-   If you want to beta test it, please `get in touch`_ with us so we can give you early access.
-
-.. _get in touch: mailto:[email protected]?subject=APIv3%20beta%20test
-
 .. contents:: Table of contents
    :local:
    :backlinks: none
@@ -37,6 +24,11 @@ Token
 The ``Authorization`` HTTP header can be specified with ``Token <your-access-token>``
 to authenticate as a user and have the same permissions that the user itself.
 
+.. note::
+
+   You will find your access Token under
+   `your profile settings <https://readthedocs.org/accounts/tokens/>`_.
+
 
 Session
 ~~~~~~~

readthedocs/profiles/urls/private.py

@@ -35,9 +35,19 @@
 tokens_urls = [
     url(
         r'^tokens/$',
-        views.TokenList.as_view(),
+        views.TokenListView.as_view(),
         name='profiles_tokens',
     ),
+    url(
+        r'^tokens/create/$',
+        views.TokenCreateView.as_view(),
+        name='profiles_tokens_create',
+    ),
+    url(
+        r'^tokens/delete/$',
+        views.TokenDeleteView.as_view(),
+        name='profiles_tokens_delete',
+    ),
 ]
 
 urlpatterns += tokens_urls

readthedocs/profiles/views.py

@@ -10,7 +10,7 @@
 from django.shortcuts import get_object_or_404, redirect, render
 from django.urls import reverse
 from django.utils.translation import ugettext_lazy as _
-from django.views.generic import ListView
+from django.views.generic import ListView, DeleteView, View
 from rest_framework.authtoken.models import Token
 
 from readthedocs.core.forms import UserAdvertisingForm, UserDeleteForm
@@ -213,22 +213,43 @@ def account_advertising(request):
 
 class TokenMixin:
 
-    """Environment Variables to be added when building the Project."""
+    """Mixin class to handle API Tokens."""
 
     model = Token
-    lookup_url_kwarg = 'token_pk'
+
+    def get_success_url(self):
+        return reverse('profiles_tokens')
+
+
+class TokenListView(TokenMixin, ListView):
+
+    """View to list all the Tokens that belong to a User."""
+
     template_name = 'profiles/private/token_list.html'
 
     def get_queryset(self):
-        # Token has a OneToOneField relation with User
+        # NOTE: we are currently showing just one token since the DRF model has
+        # a OneToOneField relation with User. Although, we plan to have multiple
+        # scope-based tokens.
         return Token.objects.filter(user__in=[self.request.user])
 
-    def get_success_url(self):
-        return reverse(
-            'projects_token',
-            args=[self.get_project().slug],
-        )
 
+class TokenCreateView(TokenMixin, View):
+
+    """Simple view to generate a Token object for the logged in User."""
+
+    http_method_names = ['post']
+
+    def post(self, request, *args, **kwargs):
+        _, created = Token.objects.get_or_create(user=self.request.user)
+        if created:
+            messages.info(request, 'API Token created successfully.')
+        return HttpResponseRedirect(self.get_success_url())
+
+
+class TokenDeleteView(TokenMixin, DeleteView):
+
+    """View to delete/revoke the current Token of the logged in User."""
 
-class TokenList(TokenMixin, ListView):
-    pass
+    def get_object(self, queryset=None):
+        return self.request.user.auth_token

readthedocs/rtd_tests/tests/test_profile_views.py

@@ -3,6 +3,7 @@
 from django.test import TestCase
 from django.urls import reverse
 from django_dynamic_fixture import get
+from rest_framework.authtoken.models import Token
 
 
 class ProfileViewsTest(TestCase):
@@ -106,3 +107,31 @@ def test_account_advertising(self):
         self.assertEqual(resp['Location'], reverse('account_advertising'))
         self.user.profile.refresh_from_db()
         self.assertFalse(self.user.profile.allow_ads)
+
+    def test_list_api_tokens(self):
+        resp = self.client.get(reverse('profiles_tokens'))
+        self.assertEqual(resp.status_code, 200)
+        self.assertContains(resp, 'No API Tokens currently configured.')
+
+        Token.objects.create(user=self.user)
+        resp = self.client.get(reverse('profiles_tokens'))
+        self.assertEqual(resp.status_code, 200)
+        self.assertContains(resp, f'Token: {self.user.auth_token.key}')
+
+    def test_create_api_token(self):
+        self.assertEqual(Token.objects.filter(user=self.user).count(), 0)
+
+        resp = self.client.get(reverse('profiles_tokens_create'))
+        self.assertEqual(resp.status_code, 405)  # GET not allowed
+
+        resp = self.client.post(reverse('profiles_tokens_create'))
+        self.assertEqual(resp.status_code, 302)
+        self.assertEqual(Token.objects.filter(user=self.user).count(), 1)
+
+    def test_delete_api_token(self):
+        Token.objects.create(user=self.user)
+        self.assertEqual(Token.objects.filter(user=self.user).count(), 1)
+
+        resp = self.client.post(reverse('profiles_tokens_delete'))
+        self.assertEqual(resp.status_code, 302)
+        self.assertEqual(Token.objects.filter(user=self.user).count(), 0)

readthedocs/templates/profiles/private/token_list.html

@@ -9,16 +9,21 @@
 {% block edit_content_header %} {% trans "API Tokens" %} {% endblock %}
 
 {% block edit_content %}
-  <p class="empty">
-    {% blocktrans trimmed with contact_email="[email protected]" %}
-      API Tokens are currently an invite-only Beta feature.
-      In case you want to test APIv3 and give us feedback on it,
-      please <a href="mailto:{{ contact_email }}">email us</a>.
-    {% endblocktrans %}
-  </p>
-
   <p>Personal Access Token are tokens that allow you to use the Read the Docs APIv3 being authenticated as yourself. See <a href="https://docs.readthedocs.org/page/api/v3.html">APIv3 documentation</a> for more information.</p>
 
+  {% if not object_list %}
+    <div class="button-bar">
+      <ul>
+        <li>
+          <form method="post" action="{% url "profiles_tokens_create" %}">
+            {% csrf_token %}
+            <input type="submit" value="{% trans "Generate API Token" %}">
+          </form>
+        </li>
+      </ul>
+    </div>
+  {% endif %}
+
     <div class="module">
       <div class="module-list">
         <div class="module-list-wrapper">
@@ -27,6 +32,16 @@
               <li class="module-item">
                   <div>Created: {{ token.created }}</div>
                   <div>Token: {{ token.key }}</div>
+
+                  <ul class="module-item-menu">
+                    <li>
+                      <form method="post" action="{% url "profiles_tokens_delete" %}">
+                        {% csrf_token %}
+                        <input type="submit" value="{% trans "Revoke" %}">
+                      </form>
+                    </li>
+                  </ul>
+
               </li>
             {% empty %}
               <li class="module-item">