diff --git a/docs/webhook2fedmsg/apid.rst b/docs/webhook2fedmsg/apid.rst
new file mode 100644
index 0000000..3ddc7d4
--- /dev/null
+++ b/docs/webhook2fedmsg/apid.rst
@@ -0,0 +1,26 @@
+.. _apid:
+
+API documentation
+=================
+
+Suggestion
+----------
+
+It is strongly recommended to automate the process of documenting API routes
+using libraries like Swagger UI and a documentation format that is compliant
+with the OpenAPI standards. To that extent, the API service library should be
+selected in a way that causes little to no concern in integrating an automated
+API documentation system.
+
+This can ensure that not only little effort is spent on the documentation but
+can also help avoid human errors that might creep in when documenting the
+routes, the expected request contents and the inferred response contents. The
+API documentation might need a test access token with limited privileges if
+present beyond authentication.
+
+Technologies
+------------
+
+1. `Swagger UI <https://swagger.io/tools/swagger-ui/>`_
+2. `OpenAPI standard <https://www.openapis.org/>`_
+