Most of the API endpoints in this repo are for internal use. These are all defined within top-level folders under app/ and tend to have the structure app/<feature>/rest.py.
Public APIs are intended for use by services and are all located under app/v2/ to distinguish them from internal endpoints. Originally we did have a "v1" public API, where we tried to reuse / expose existing internal endpoints. The needs for public APIs are sufficiently different that we decided to separate them out. Any "v1" endpoints that remain are now purely internal and no longer exposed to services.
Here are some pointers for how we write public API endpoints.
Example: app/v2/inbound_sms/get_inbound_sms.py
This helps keep the file size manageable but does mean a bit more work to register each endpoint if we have many that are related. Note that internal endpoints are grouped differently: in large rest.py files.
Example:
from flask import Blueprint
from app.v2.errors import register_errors
v2_notification_blueprint = Blueprint("v2_notifications", __name__, url_prefix='/v2/notifications')
register_errors(v2_notification_blueprint)
Note that the error handling setup by register_errors (defined in app/v2/errors.py) for public API endpoints is different to that for internal endpoints (defined in app/errors.py).
Example: Ruby Client adapter to get template by ID.
All our clients should fully support all of our public APIs.
Each adapter should be documented in each client (example). We should also document each public API endpoint in our generic API docs (example). Note that internal endpoints are not documented anywhere.
This is done as part of registering the blueprint in app/__init__.py e.g.
post_broadcast.before_request(requires_auth)
application.register_blueprint(post_broadcast)