:PROPERTIES:
:ID:       a81b2ff0-5ede-44b3-8f82-960357f15428
:END:
#+title: Python Services
#+OPTIONS: ^:nil
#+PROPERTY: header-args :exports code

* Platform
- Python 3.9[fn:programming-languages]
- Tornado 6[fn:frameworks]

* Code Style
Code style must be enforced using flake8.[fn:python-lint-checking]

#+begin_example
  [flake8]
  application-import-names = PACKAGE_NAME,tests
  exclude = build,env
  import-order-style = pycharm
#+end_example
* Requirements
** Uncaught errors are logged and alerted via Sentry
#+NAME: packages
- =sentry-sdk=

  #+begin_src python
    from sentry_sdk import init
    init(SENTRY_DSN)
  #+end_src

** A status endpoint is exposed
The endpoint should be provide the following fields:
- application :: The name of the service
- environment :: The operating environment the instance of the service is
  running in (i.e. "development", "testing", "staging" or "production")
- status :: Current service status (e.g.: "ok", "starting")
- version :: Packaged version of the service instance
- python_version :: The python version running the service instance
  (=platform.python_version()=)

  The endpoint should return =200= when the service is healthy, and =503= if the
  service is not ready to serve requests.
** The service self-hosts its API documentation
An OpenAPI specification is hosted using ReDoc at the root service URL.[fn:backend-services]
** Test coverage reports are available in SonarQube
** Structured logging
json-scribe
** Provides consistent error responses
json-problem
** The service represents itself using its service name and version
- The service must include its name and version in its =Server= response header.[fn:response-headers]
- The service must include its name and version in the =User-Agent= header for all its HTTP requests.[fn:user-agent]

  Both of these should be presented as =${service-name}/${version}=, e.g.:
  =user-management/1.0.0=.
* References
- [[https://confluence.aweber.io/display/STD/Back+End+Services]]

* Footnotes

[fn:user-agent] https://confluence.aweber.io/display/STD/RESTful+APIs#heading-User-AgentRequestHeader
[fn:response-headers] https://confluence.aweber.io/display/STD/RESTful+APIs#heading-ResponseHeaders

[fn:backend-services] https://confluence.aweber.io/display/STD/Back+End+Services

[fn:frameworks] https://confluence.aweber.io/display/STD/Development+Frameworks

[fn:python-lint-checking] https://confluence.aweber.io/display/STD/Python+Lint+Checking

[fn:programming-languages] https://confluence.aweber.io/display/STD/Programming+Languages