API projects

Many of the Maykin projects are API-first projects with only a minimum of “public frontend” requirements. maykin-common facilitates these by providing some base templates, CSS and JS for the landing page.

Templates

Two templates are provided from the library that you should extend:

• maykin_common/api/index_base.html, use it in index.html for your landing page

• maykin_common/api/includes/footer.html, use it to extend your includes/footer.html from

If your project has multiple API components, there is a third template you should extend to create the page for each component.

• maykin_common/api/index_component.html, use it in api_component.html for your API component page.

You’ll need to make some modifications to the root urls.py and master.html to wire up everything automatically.

Tip

With the default project setup, the necessary CSS and Javascript are automatically loaded. If you use another master template, make sure to define the view_class, extra_css and content blocks to override.

maykin_common/api/index_base.html

Provides the general scaffolding of the language page with the tabbed layout for Dutch and English content and the general branding.

In your child template, make sure to override the blocks that are specific to your project:

• page_title

• page_subtitle

• content_nl

• content_en

• license_link

• api_links

Tip

The base template defines a block called api_links that displays two links for the API interface: API docs (ReDoc) and Open API specification. If the variables api_docs_link and api_schema_link are not provided to the template, the fallback values default_api_docs_link and default_api_schema_link are used instead. A child template can override the api_links block and explicitly provide the URLs.

For example:

{% block api_links %}

    {% url 'schema-redoc' version=version as api_docs_link %}
    {% url 'schema-json' as api_schema_link %}

    {% with api_docs_link=api_docs_link api_schema_link=api_schema_link %}
        {{ block.super }}
    {% endwith %}

{% endblock %}

Tip

To add extra buttons next to the api_links in the template, use the extra_buttons block. This allows you to include custom actions without modifying the base template.

maykin_common/api/index_component.html

Provides the standard initialization for an API component page and contains the links for api_docs, api_schema and notifications.

In your child template, make sure to override the blocks that are specific to your API component:

• page_title

• page_subtitle

• title_component

• subtitle_component

• api_links

maykin_common/api/includes/footer.html

Provides the standard footer layout with sensible defaults. You can override (default) values by clever usage of the with tag:

{% block footer %}
    {% capture as issues_link silent %}<a class="link link--muted" href="https://github.com/maykinmedia/awesome-project/issues">issues</a>{% endcapture %}

    {% with issues_link=issues_link %}
        {{ block.super }}
    {% endwith %}

{% endblock %}

Tip

Consider installing django-capture-tag for cleaner templates, like the example above.

Tip

To add extra buttons next to the api_links in the template, use the extra_buttons block. This allows you to include custom actions without modifying the base template.

Blocks you’ll typically want to override are:

• footer

• links - the middle column with project-specific links

Other blocks you can override are:

• other_links - the links in the rightmost column

Stylesheets

The base template automatically loads the maykin_common/css/api.css stylesheets which contains the majority of the styles for the landing page components.

Note

While the default template uses font-awesome class names, the font-awesome stylesheet is not included as we want to avoid any frontend toolchains as long as possible. You have to make sure your project includes the styles and font assets yourself.

Tip

No default values are provided, however the default-project template does provide a starter setup in the _os_api directory.

The CSS is written with theming in mind. At the time of writing, the following CSS variables are supported, grouped by component:

Page title

• --page-title-color

• --page-title-font-family

Footer

• --footer-border-color

Tabs

• --tabs-border-color

• --tabs-item-color

• --tabs-item-hover-color

• --tabs-item-hover-border-color

Button

• --button-color

• --button-background-color

• --button-hover-background-color

• --button-alert-background-color

• --button-alert-hover-background-color

Link

• --link-color

• --link-color-hover

• --link-color-muted

Javascript

We ship a minimal amount of Javascript and it’s automatically loaded from the base template.

maykin_common/js/nav-tabs.js

Controls the (active) tab state for the .tabs component.