Django API Playground

Hipo was in dire need of a testing console in order to test the API’s we’d written, but our research to find a good one proved fruitless. Since we could find no API consoles for Django that matched our needs, we set out to build our own. The brief was to create a solid testing platform for us and the developers who would use our API’s.

The result is below. We called it the Django API Playground. In addition to being a testing console, the app allows developers to comment and respond to the results from the API, making this a great feedback mechanism as well.

In this article, we’ll demonstrate how to install and use the Django API Playground.

You can find the app demo below:

http://api-playground-demo.hipo.biz

Installation

Let’s start by installing the django-api-playground package.

pip install git+git://github.com/Hipo/Django-API-Playground.git

Then you add the apiplayground package to INSTALLED_APPS found in the settings.py file of your Django project.

INSTALLED_APPS =(
    # ...
    'apiplayground',
)

We can now define a Playground. Create a playground.py file where you store your API. The modules content should look like this:

# api/playgrounds.py

from apiplayground import APIPlayground

class ExampleAPIPlayground(APIPlayground):

    schema = {
        "title": "API Playground",
        "base_url": "http://localhost/api/",
        "resources": [
            {
                "name": "/feedbacks",
                "description": "This resource allows you to manage feedbacks.",
                "endpoints": [
                    {
                        "method": "GET",
                        "url": "/api/feedbacks/{feedback-id}",
                        "description": "Returns a specific feedback item"
                    },
                    {
                        "method": "POST",
                        "url": "/api/feedbacks/",
                        "description": "Creates new feedback item",
                        "parameters": [{
                            "name": "title",
                            "type": "string"
                        },
                        {
                            "name": "resource",
                            "type": "string"
                        },
                        {
                           "name": "description",
                           "type": "string"
                        }]
                    }
                ]
            },
        ]
    }

In this example, we create a different class from the class APIPlayground, and define the API Resources that we want in our console. As you can see, it’s a pretty simple process. We’ll publish a more detailed documentation on this soon.

And now, it’s time to define your URL’s

# urls.py

from api.playgrounds import ExampleAPIPlayground

urlpatterns = patterns('',
    (r'api-explorer/', include(ExampleAPIPlayground().urls)),
)

And with that, your API Playground is ready for action.

Let’s build it together!

If you find the project interesting, you can help improve it through Github. Here is what you can help us with:

  • If you catch an error, please report it through issues
  • If you have an extra feature in mind that will make this project better, please share.
  • If you want to help directly, by all means fork the project and create your own improvements.
  • If you can help with creating the documentation, that would also be great.

The Github repo of this project can be found here:

https://github.com/Hipo/django-api-playground