OpenAPI and DRF Serializers

OpenAPI

Describes a RESTful API

```yaml
              openapi: 3.0.2
info:
  title: Customers
  version: 0.1.0
  description: API for customers
paths:
  /customers/:
    get:
      operationId: listUsers
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    id:
                      type: integer
                      readOnly: true
                    username:
                      type: string
                      description: Required. 150 characters or fewer. Letters, digits
                        and @/./+/-/_ only.
                      pattern: ^[\w.@+-]+$
                      maxLength: 150
                    email:
                      type: string
                      format: email
                      maxLength: 254
                    first_name:
                      type: string
                      maxLength: 30
                    last_name:
                      type: string
                      maxLength: 150
                  required:
                  - username
          description: ''
    post:
      operationId: createUser
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                username:
                  type: string
                  description: Required. 150 characters or fewer. Letters, digits
                    and @/./+/-/_ only.
                  pattern: ^[\w.@+-]+$
                  maxLength: 150
                email:
                  type: string
                  format: email
                  maxLength: 254
                first_name:
                  type: string
                  maxLength: 30
                last_name:
                  type: string
                  maxLength: 150
              required:
              - username
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: integer
                    readOnly: true
                  username:
                    type: string
                    description: Required. 150 characters or fewer. Letters, digits
                      and @/./+/-/_ only.
                    pattern: ^[\w.@+-]+$
                    maxLength: 150
                  email:
                    type: string
                    format: email
                    maxLength: 254
                  first_name:
                    type: string
                    maxLength: 30
                  last_name:
                    type: string
                    maxLength: 150
                required:
                - username
          description: ''
  /customers/{id}/:
    get:
      operationId: retrieveUser
      parameters:
      - name: id
        in: path
        required: true
        description: A unique integer value identifying this user.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: integer
                    readOnly: true
                  username:
                    type: string
                    description: Required. 150 characters or fewer. Letters, digits
                      and @/./+/-/_ only.
                    pattern: ^[\w.@+-]+$
                    maxLength: 150
                  email:
                    type: string
                    format: email
                    maxLength: 254
                  first_name:
                    type: string
                    maxLength: 30
                  last_name:
                    type: string
                    maxLength: 150
                required:
                - username
          description: ''
    put:
      operationId: updateUser
      parameters:
      - name: id
        in: path
        required: true
        description: A unique integer value identifying this user.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                username:
                  type: string
                  description: Required. 150 characters or fewer. Letters, digits
                    and @/./+/-/_ only.
                  pattern: ^[\w.@+-]+$
                  maxLength: 150
                email:
                  type: string
                  format: email
                  maxLength: 254
                first_name:
                  type: string
                  maxLength: 30
                last_name:
                  type: string
                  maxLength: 150
              required:
              - username
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: integer
                    readOnly: true
                  username:
                    type: string
                    description: Required. 150 characters or fewer. Letters, digits
                      and @/./+/-/_ only.
                    pattern: ^[\w.@+-]+$
                    maxLength: 150
                  email:
                    type: string
                    format: email
                    maxLength: 254
                  first_name:
                    type: string
                    maxLength: 30
                  last_name:
                    type: string
                    maxLength: 150
                required:
                - username
          description: ''
    patch:
      operationId: partial_updateUser
      parameters:
      - name: id
        in: path
        required: true
        description: A unique integer value identifying this user.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                username:
                  type: string
                  description: Required. 150 characters or fewer. Letters, digits
                    and @/./+/-/_ only.
                  pattern: ^[\w.@+-]+$
                  maxLength: 150
                email:
                  type: string
                  format: email
                  maxLength: 254
                first_name:
                  type: string
                  maxLength: 30
                last_name:
                  type: string
                  maxLength: 150
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: integer
                    readOnly: true
                  username:
                    type: string
                    description: Required. 150 characters or fewer. Letters, digits
                      and @/./+/-/_ only.
                    pattern: ^[\w.@+-]+$
                    maxLength: 150
                  email:
                    type: string
                    format: email
                    maxLength: 254
                  first_name:
                    type: string
                    maxLength: 30
                  last_name:
                    type: string
                    maxLength: 150
                required:
                - username
          description: ''
    delete:
      operationId: destroyUser
      parameters:
      - name: id
        in: path
        required: true
        description: A unique integer value identifying this user.
        schema:
          type: string
      responses:
        '204':
          description: ''
              ```

Is it useful?

Autogenerate client (see apistar)
Automatic documentation (supports confluence)
Language agnostic
Mock API servers
Automated tests for your API (eg: soapui)

How are serializers related to openAPI?

what

Most of DRF elements (serializers, filters, responses)

map directly to a part of a REST API

Serializers map directly to the HTTP BODY

(THE PAYLOAD)

What are they for?

Do's and Don'ts of serializers

Do's

✔ Validate input data
✔ Clean input data
✔ Deserialize (most of the times)

Don'ts

❌ Querystrings
❌ Headers
❌ Pagination
❌ input/output serializers

Do we need output serializer?

Does it have an impact on performance?

No, we don't need them

Yes, it has an impact on performance

output serializer is 41% slower

540.8ms vs 917.4ms on average

(sorry for the cheap benchmarks)

Some alternatives

✔Follow REST principles and work with the same resource
✔Use read_only_fields or write_only
✔Use to_representation or to_internal_value

DRY

Some stats:

APIView: 278

ModelViewSet: 17

APIView vs ViewSet -- DEMO TIME

on_fire

How to deal with querystrings?

Django filter

Similar to serializers (declarative)
Can raise 400s if needed
Creates OpenAPI representation

Dealing with sensitive information in querystrings

use HEADERS

Find me on twitter

@santiwilly