A Documentation-Driven Approach to Building APIs

Slide 1

Slide 1 text

A DOCUMENTATION-DRIVEN APPROACH TO BUILDING APIS USING DJANGO REST FRAMEWORK AND OPENAPI Stephen Finucane (@stephenﬁn) Python Ireland Remote MeetUp, May 2020

Slide 2

Slide 2 text

ABOUT ME Senior Software Engineer at Red Hat Working on OpenStack since ~2015 Working on Python for even longer

Slide 3

Slide 3 text

AGENDA Intro to Django and Django REST Framework Intro to OpenAPI Generating an OpenAPI schema with DRF Validating a DRF-based API with OpenAPI Documenting Your API Wrap Up

Slide 4

Slide 4 text

Intro to Django and Django REST Framework

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design. Built by experienced developers, it takes care of much of the hassle of Web development, so you can focus on writing your app without needing to reinvent the wheel. It’s free and open source.

Slide 8

Slide 8 text

No content

Slide 9

Slide 9 text

Django REST framework is a powerful and ﬂexible toolkit for building Web APIs that includes a web browsable API, serialization that supports both ORM and non-ORM data sources, extensive documentation and a large community.

Slide 10

Slide 10 text

No content

Slide 11

Slide 11 text

$ django-admin startproject mysite $ ls mysite/ manage.py mysite/ __init__.py settings.py urls.py asgi.py wsgi.py

Slide 12

Slide 12 text

$ cd myapp $ python manage.py startapp core $ ls core/ __init__.py admin.py apps.py migrations/ __init__.py models.py tests.py views.py

Slide 13

Slide 13 text

class Post(models.Model): title = models.CharField(max_length=255) date = models.DateTimeField(auto_now_add=True) author = models.ForeignKey( User, on_delete=models.CASCADE, ) body = models.TextField() mysite/core/models.py

Slide 14

Slide 14 text

class PostSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = Post fields = ['url', 'title', 'date', 'author', 'body'] class UserSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = User fields = ['url', 'username', 'email'] mysite/core/serializers.py

Slide 15

Slide 15 text

class PostViewSet(viewsets.ModelViewSet): queryset = Post.objects.all() serializer_class = PostSerializer permission_classes = [ permissions.IsAuthenticatedOrReadOnly] class UserViewSet(viewsets.ModelViewSet): queryset = User.objects.all().order_by('-date_joined') serializer_class = UserSerializer permission_classes = [permissions.IsAuthenticated] mysite/core/views.py

Slide 16

Slide 16 text

router = routers.DefaultRouter() router.register(r'users', views.UserViewSet) router.register(r'posts', views.PostViewSet) urlpatterns = [ path('', include(router.urls)), ] mysite/mysite/urls.py

Slide 17

Slide 17 text

$ python manage.py runserver 0.0.0.0:8000

Slide 18

Slide 18 text

$ curl -s http://localhost:8000/posts/ | python -m json.tool { "count": 0, "next": null, "previous": null, "results": [] }

Slide 19

Slide 19 text

$ curl -s http://localhost:8000/posts/ | python -m json.tool { "count": 1, "next": null, "previous": null, "results": [ { "url": "http://localhost:8000/posts/1/", "title": "Hello, world", "date": "2020-05-13T09:58:54.805866Z", "author": "http://localhost:8000/users/1/", "body": "This is my first post." } ] }

Slide 20

Slide 20 text

No content

Slide 21

Slide 21 text

No content

Slide 22

Slide 22 text

Intro to OpenAPI

Slide 23

Slide 23 text

No content

Slide 24

Slide 24 text

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

Slide 25

Slide 25 text

openapi: 3.0.0 info: title: Sample API version: 0.1.9 servers: - url: http://api.example.com/v1 paths: /users: get: summary: Returns a list of users. responses: '200': # status code content: application/json: schema: type: array items: type: string

Slide 26

Slide 26 text

Generating an OpenAPI schema with DRF

Slide 27

Slide 27 text

$ python manage.py generateschema

Slide 28

Slide 28 text

$ python manage.py generateschema openapi: 3.0.2 info: title: '' version: '' paths: /users/: get: operationId: listUsers description: API endpoint that allows users to be viewed or edited. parameters: - name: page required: false description: A page number within the paginated result set. schema: type: integer responses: # ...

Slide 29

Slide 29 text

# ... responses: '200': content: application/json: schema: type: object properties: count: type: integer example: 123 next: type: string nullable: true previous: type: string nullable: true # ...

Slide 30

Slide 30 text

Documenting Your API

Slide 31

Slide 31 text

urlpatterns = [ path('', include(router.urls)), path('openapi', get_schema_view( title='Your Project', description='API for all things …', version='1.0.0' ), name='openapi-schema'), path('swagger-ui/', TemplateView.as_view( template_name='swagger-ui.html', extra_context={'schema_url': 'openapi-schema'} ), name='swagger-ui'), ] mysite/mysite/urls.py

Slide 32

Slide 32 text

No content

Slide 33

Slide 33 text

No content

Slide 34

Slide 34 text

extensions = [ 'sphinxcontrib.openapi', ] mysite/docs/conf.py

Slide 35

Slide 35 text

============ Sample API ============ .. openapi:: openapi.yml mysite/docs/index.rst

Slide 36

Slide 36 text

No content

Slide 37

Slide 37 text

extensions = [ 'sphinxcontrib.redoc', ] redoc = [ { 'name': 'Sample API', 'page': 'api/index', 'spec': 'openapi.yml', 'embed': True, }, ] mysite/docs/conf.py

Slide 38

Slide 38 text

============ Sample API ============ .. toctree:: :glob: api/* mysite/docs/index.rst

Slide 39

Slide 39 text

No content

Slide 40

Slide 40 text

Validating a DRF-based API with OpenAPI

Slide 41

Slide 41 text

No content

Slide 42

Slide 42 text

ROOT_DIR = os.path.join(os.path.dirname(__file__), os.pardir) SCHEMA = os.path.join(ROOT_DIR, 'docs', 'openapi.yml') class SchemaValidationTests(TestCase): def test_validate_schema(self): with open(SCHEMA) as fh: schema = yaml.safe_load(fh) openapi_spec_validator.validate_spec(schema) mysite/core/tests.py

Slide 43

Slide 43 text

$ python manage.py test core Creating test database for alias 'default'... System check identified no issues (0 silenced). . -------------------------------------------------------------------- Ran 1 test in 0.114s OK Destroying test database for alias 'default'...

Slide 44

Slide 44 text

No content

Slide 45

Slide 45 text

from django.test.client import RequestFactory from openapi_core.validation.request.validators import ( RequestValidator) from openapi_core.contrib.django import DjangoOpenAPIRequest request_factory = RequestFactory() django_request = request_factory.get('/posts/') openapi_request = DjangoOpenAPIRequest(django_request) validator = RequestValidator(spec) result = validator.validate(openapi_request) assert not result.errors, result.errors

Slide 46

Slide 46 text

No content

Slide 47

Slide 47 text

Wrap Up

Slide 48

Slide 48 text

WRAP UP Use Django + Django REST Framework for fast APIs Generate or handwrite OpenAPI schemas Use these schemas for documentation Use these schemas for validation (server and client)

Slide 49

Slide 49 text

FURTHER READING Transparent validation of requests/responses Auto-generation of APIs Auto-generation of clients ...

Slide 50

Slide 50 text

A DOCUMENTATION-DRIVEN APPROACH TO BUILDING APIS USING DJANGO REST FRAMEWORK AND OPENAPI Stephen Finucane (@stephenﬁn) Python Ireland Remote MeetUp, May 2020

Slide 51

Slide 51 text

Resources ● Cover Photo by Alain Pham on Unsplash

Slide 52

Slide 52 text

References ● Getting started (docs.djangoproject.com) ● Quickstart (django-rest-framework.org) ● Documenting your API (django-rest-framework.org) ● openapi-core 0.13.3 (PyPI)