Following last week's launch of a new series of articles on LinkedIn, there is now a refresh under a new name on the codecentric blog. Why "Charge your APIs"? Quite simply, we all need to think APIs further and not just see them as a vehicle for integration. But for that, there is a lot to do besides the classic API design. That's why I would like to pick a particular topic each week and look at it in more detail. And I'll also tell you one or two tricks from our everyday project work. And here we go! Last week's focus was on Any Decision Records (ADRs). The Decision Records served as a starting point. Now, this week, we want to build the foundation for the creation of relevant API guidelines. At this point, I would like to define again what API guidelines actually are.
Refreshing API-Guidelines
API guidelines are a set of rules and recommendations that should be considered when developing and using APIs. These guidelines can refer to various aspects of API design, such as the naming of endpoints, the use of HTTP methods, the handling of error messages or the documentation of interfaces.
The goal of API guidelines is to increase the consistency and usability of APIs to ensure a better experience for developers and users. Well-designed APIs that follow the guidelines can also contribute to easier maintenance, scalability and integration of applications.
A bit more information on API guidelines can be found in my post on Medium.
Now, if we want to create API guidelines, we can do so using any editor and store them in a central location in the organisation. The writing process and storage are only part of the whole. We have already set the textual foundation with ADRs. From them, we now want to create the documentation for our API initiative. In the context of documentation systems, static site generators are becoming more and more common.
Static Site Generator
A static site generator is a tool used to create static websites. Unlike dynamic websites, which use databases and server-side scripts, static websites generate all pages in advance and store them on the server. The generator uses a template and content in the form of text, images, etc. and generates the static HTML files for the website. Static site generators enable faster and more secure website development, as no server-side processing is necessary and content can be cached more efficiently. They are also great for creating documentation, as in the context of API guidelines, as they make it easier to create and manage content in a central data source.
Building a documentation system with mkdocs
Today I'd like to take a look at mkdocs. A very lightweight system based on Python and Markdown. After installing mkdocs, you can start right away.
1❯ mkdocs new acme-api-initiative 2INFO - Creating project directory: acme-api-initiative 3INFO - Writing config file: acme-api-initiative/mkdocs.yml 4INFO - Writing initial docs: acme-api-initiative/docs/index.md
With the creation of the directory for the ACME API initiative, we have laid the foundation. With the possibility of using plugins and templates to customise the functionality and presentation of mkdocs, we can build a documentation system that meets our needs. Here is a first basic configuration:
1site_name: ACME API Initiative Documentation 2 3plugins: 4 - search 5 - multirepo: 6 cleanup: true 7 keep_docs_dir: true 8 repos: 9 - section: Decision Records 10 import_url: 'https://github.com/danielkocot/decision_records_example?branch=main&docs_dir=*' 11 12theme: 13 name: material 14 palette: 15 - media: "(prefers-color-scheme: light)" 16 scheme: default 17 toggle: 18 icon: material/brightness-7 19 name: Switch to dark mode 20 - media: "(prefers-color-schema: dark)" 21 scheme: slate 22 toggle: 23 icon: material/brightness-4 24 name: Switch to light mode
In this configuration, I use an integrated plugin for the search function and the mkdocs-multirepo-plugin in addition to mkdocs-material. The last plugin makes it possible to integrate external documentation repositories into the documentation system. Specifically, this is now the Decision Records from last week. With mkdocs-material, a few little helpers, such as Python Markdown Extensions, are added in addition to the actual theme. One special feature should be noted: mkdocs-material is available as an open source variant and as an Insiders fork, which is available for a monthly sponsorship. This is a good thing, as it keeps the project alive in the long term and, via Funding Goals, all users get access to all functions over time. But back to our initiative documentation. For the first time, we will now create it using mkdocs serve.
1❯ mkdocs serve 2INFO - Building documentation... 3INFO - Multirepo plugin importing docs... 4✅ decision-records (1.162 secs) 5INFO - Cleaning site directory 6INFO - Multirepo plugin is cleaning up temp_dir/ 7INFO - Documentation built in 1.33 seconds 8INFO - [01:05:39] Watching paths for changes: 'docs', 'mkdocs.yml' 9INFO - [01:05:39] Serving on http://127.0.0.1:8000/ 10INFO - [01:05:39] Browser connected: http://localhost:8000/
If we now go to http://localhost:8000 in the browser, we get the following view.
So the documentation works already locally, but will reach so few to no one 😉 . Therefore, we need a central place where the documentation can be accessed. Since the decision records can be found on Github anyway, this is also a good place for the documentation. So we now create an action based on mkdocs-deploy-gh-pages. Before we look at the action further, we have to create a requirements.txt for the mkdocs plugins, because we need exactly the dependencies for the respective runs of the action.
1❯ pip freeze > requirements.txt
1name: Publish docs via GitHub Pages 2on: 3 push: 4 branches: 5 - main 6 7jobs: 8 build: 9 name: Deploy docs 10 runs-on: ubuntu-latest 11 steps: 12 - name: Checkout main 13 uses: actions/checkout@v2 14 15 - name: Deploy docs 16 uses: mhausenblas/mkdocs-deploy-gh-pages@master 17 # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme 18 env: 19 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 20 AccessToken: $(System.AccessToken) 21 CONFIG_FILE: mkdocs.yml 22 EXTRA_PACKAGES: build-base 23 # GITHUB_DOMAIN: github.myenterprise.com 24 REQUIREMENTS: requirements.txt
With each push, the Github Action is executed and creates a new version of the documentation.
Conclusion
As we have seen, the development of a documentation system, which can also grow into a documentation platform, is possible with little programming effort, almost low-code-like. mkdocs with all its plug-ins and perhaps one or two of our own developments will accompany us on our way in the coming weeks. Next week we'll be looking in the direction of the API guidelines. So long!
References
GitHub - danielkocot/decision_records_example
GitHub - danielkocot/acme-api-initiative: An example for a documentation platform with mkdocs
Photo by Maksym Kaharlytskyi on Unsplash
Was this post helpful?
More articles
fromDaniel Kocot
16.4.2024 Your job at codecentric?
Jobs
Agile Developer und Consultant (w/d/m)
Alle Standorte
More articles in this subject area
Discover exciting further topics and let the codecentric world inspire you.
Gemeinsam bessere Projekte umsetzen.
Wir helfen deinem Unternehmen.
Du stehst vor einer großen IT-Herausforderung? Wir sorgen für eine maßgeschneiderte Unterstützung. Informiere dich jetzt.
Hilf uns, noch besser zu werden.
Wir sind immer auf der Suche nach neuen Talenten. Auch für dich ist die passende Stelle dabei.
Blog author
Daniel Kocot
Senior Solution Architect / Head of API Consulting
Do you still have questions? Just send me a message.
Do you still have questions? Just send me a message.