Welcome to Know Me API’s documentation!¶
Know Me API¶
- API Root
- https://toolbox.knowmetools.com
- API Endpoint Documentation
- https://toolbox.knowmetools.com/docs/
- Developer Documentation
- http://know-me-api.readthedocs.io/
About¶
This is the API behind our Know Me app. It is written in Python using Django and Django Rest Framework.
Deployment¶
Changes to this repository are automatically deployed based on the configuration in our deployment repository.
Development¶
The API is built with Python using Django and Django Rest Framework.
Recommended Development Environment¶
If you are comfortable with setting up a python development environment and cloning the project, feel free to skip to the development environment overview.
Prerequisites¶
We use git for version control and follow the general pattern of always having a production-ready master branch with features developed on short-lived branches.
This project runs on Python 3.6. You must have Python 3.6 installed to contribute. If you do not have it installed, you can find it here. To manage third-party Python packages, we use pipenv.
Project Setup¶
The first step is to clone the environment:
$ git clone git@github.com:knowmetools/km-api
# Or, if you don't have SSH access
$ git clone https://github.com/knowmetools/km-api
# The remaining commands require you to be in the project directory
$ cd km-api/
Next, install the project requirements
$ pipenv install --dev
The final step is to create a .env file in the root of your project. This
file will be read by any commands executed through pipenv. For convenience,
create the file with the contents:
DJANGO_DEBUG=true
DJANGO_MEDIA_ROOT=km_api/media
Linting¶
We use a combination of flake8 and black for linting and formatting our code, respectively. To ensure that there are no formatting/linting errors on each commit, we use the pre-commit tool. To install it, simply run:
pipenv run pre-commit install
This will ensure that your code is formatted prior to every commit. If the tool is somehow circumvented or not run, our CI process also runs the same checks and will fail a build that has formatting or linting errors.
Dev Environment Overview¶
Quickstart¶
Clone the project and install the dependencies:
$ git clone git@github.com:knowmetools/km-api
$ cd km-api
$ pipenv install --dev
Local Dev Server¶
The development server can be run using the following command:
$ pipenv run km_api/manage.py migrate
$ pipenv run km_api/manage.py runserver
Running Tests¶
Tests are run with pytest. To run the tests, make sure the requirements are installed and run the tests:
$ pipenv install --dev
$ pipenv run pytest km_api/
Building Docs¶
We use sphinx for building documentation, and the docs are automatically published using ReadTheDocs. If you want to build the docs locally, install the requirements and run the build command:
$ pipenv install -r requirements/docs.txt
$ cd docs
$ pipenv run make html
Deployment¶
For an example of how to deploy the application, see knowmetools/km-api-deployment.
Environment Variables¶
The following environment variables can be used to modify the application’s behavior.
Note
The application will only attempt to use a Postgres database if all of DJANGO_DB_HOST, DJANGO_DB_NAME, DJANGO_DB_PASSWORD, DJANGO_DB_PORT, and DJANGO_DB_USER are set. If any of these settings are not provided, we fall back to a local SQLite database.
DJANGO_ALLOWED_HOSTS¶
Default: ''
A comma separated list of allowed hosts.
Note
This must be set if DJANGO_DEBUG is set to False.
DJANGO_APPLE_RECEIPT_VALIDATION_ENDPOINT¶
Default: https://sandbox.itunes.apple.com/verifyReceipt
The endpoint used to verify subscription receipts from Apple. This can take one of two values:
https://sandbox.itunes.apple.com/verifyReceipthttps://buy.itunes.apple.com/verifyReceipt
DJANGO_DB_PASSWORD¶
Default:: ''
The password of the user that the application connects to the Postgres database as.
DJANGO_EMAIL_VERIFICATION_URL¶
Default: https://example.com/verify/{key}'
The template used to construct links for verifying a user’s email address. The {key} portion of the template will be replaced with a unique token.
DJANGO_HTTPS¶
Default: False
Set to True (case insensitive) if the application is served over HTTPS.
DJANGO_HTTPS_LOAD_BALANCER¶
Default: False
Set to True (case insensitive) if the application is served over HTTPS but is located behind a load balancer that terminates SSL. If this is enabled, requests with the header HTTP_X_FORWARDED_PROTO set to https will be treated as if they came in over HTTPS.
Note
This has no effect unless DJANGO_HTTPS is set to True.
DJANGO_IN_MEMORY_FILES¶
Default: False
Set to True (case insensitive) to store static files in memory. This is mainly used for testing.
DJANGO_MEDIA_ROOT¶
Default: ''
The location on the server’s filesystem to store user uploaded files at. This setting has no effect when DJANGO_S3_STORAGE is True.
DJANGO_PASSWORD_RESET_URL¶
Default: https://example.com/reset/{key}
The template used to construct password reset links. The {key} portion of the template will be replaced with a unique token.
DJANGO_RUNNING_ON_ECS¶
Default: False
A boolean indicating if the application is running as an ECS task. If it is, the application automatically adds the private IP of the ECS task to the list of allowed hosts.
DJANGO_S3_AWS_REGION¶
Default: $DJANGO_AWS_REGION
The AWS region that the S3 bucket used to store files is located in. Only takes effect when DJANGO_S3_STORAGE is True.
DJANGO_S3_BUCKET¶
Default: ''
The name of the S3 bucket to store files in. Only takes effect when DJANGO_S3_STORAGE is True.
DJANGO_S3_STORAGE¶
Default: False
Set to True (case insensitive) to enable storage of static and user uploaded files in an S3 bucket. Requires the following settings to be provided:
DJANGO_S3_BUCKET
DJANGO_SECRET_KEY¶
Default: secret
Warning
The default value is only used if DJANGO_DEBUG is set to True. This is to avoid exposing a known secret key in a production environment.
The secret key that Django uses for a few security operations.
DJANGO_SENTRY_DSN¶
Default: ''
The Data Source Name for the application’s Sentry project. If provided logging of warnings and errors to Sentry is enabled.
DJANGO_SENTRY_ENVIRONMENT¶
Default: default
The name of the environment that should be provided as context when logging to Sentry. Only takes effect when DJANGO_SENTRY_DSN is provided.
DJANGO_SENTRY_RELEASE¶
Default: unknown
An identifier sent with all events to Sentry that lets us identify which version of the application caused the issue.
DJANGO_SES_AWS_REGION¶
Default: $DJANGO_AWS_REGION
The AWS region to send SES emails from. Only takes effect when DJANGO_SES_ENABLED is True.
DJANGO_SES_ENABLED¶
Default: False
Set to True (case insensitive) to enable sending of emails using AWS SES.
DJANGO_STATIC_ROOT¶
Default: ''
The location on the server’s filesystem to store static files at. This setting has no effect when DJANGO_S3_STORAGE is True.
Changelog¶
Warning
This changelog is no longer updated since we adopted continuous integration and deployment practices. It exists purely for historical reasons.
In Development¶
v1.5.0¶
- Features
- Miscellaneous
- Completely changed the way that settings are provided. Rather than being specified in a separate python file that is then imported, behavior is now set through environment variables.
- #383: Remove MailChimp integration.
- #384: Remove CloudWatch integration.
- #386: Remove deployment configuration. Deployment is now handled by knowmetools/km-api-deployment.
v1.4.0¶
v1.3.0¶
- Features
- #236: Add email notifications when a user is invited to view another user’s profiles.
v1.2.2¶
Fix issue where users could upgrade their own accounts to have staff permissions.
v1.2.1¶
v1.2.0¶
v1.1.0¶
v1.0.2¶
v1.0.0¶
- Breaking Changes
- #296: Add separate endpoint to accept an accessor.
- #316: Paginate journal entries. The entries are now nested under the
resultskey, and there is additional information returned such as the total number of entries and the URLs for the next and previous pages. Entries are listed in reverse chronological order. - #332: Remove ability to manually create a Know Me user. As per #263, a Know Me user is automatically created for each registered user.
- Features
- #233: Add config endpoint for Know Me app. It contains information such as the lowest useable iOS app version.
- #259: Add optional profile image for users.
- #263, #277: Automatically create a Know Me user for each user. The Know Me user’s image defaults to the user’s profile image.
- #278: Include information about the user granted access through an accessor.
- #299: Add additional information to media resources. The resources can have a link instead of a file, and they have an integer to hint how they should be styled.
- #306: Add tracking of legacy users. The list of legacy users can be viewed/updated by staff.
- #313: Expose if a user is a staff member through the profile endpoint.
- #321: Allow media resources to be detached from profile items.
- #326: The Know Me user owned by the requesting user is guaranteed to be the first element in the list returned from
/know-me/users/. Each user in the list also has a newis_owned_by_current_userboolean attribute. - #328: Increase maximum upload size to 100MB.
v0.9.3¶
- Bug Fixes
v0.9.0¶
v0.8.0¶
- Breaking Changes
- #253, #282: Massive rewrite of profile features. This is a backwards incompatible change that modifies endpoints and the data returned from profile endpoints in addition to requiring a complete database wipe.
- #258: Require multiple calls to return full profile.
- #267: Refactor accessor permission fields. The permissions are now encompassed in a single
is_adminfield.
- Features
- #246, #247, #251: Add endpoints for managing journal entries.
- #248, #249, #252: Add endpoints for managing comments on journal entries.
- #250: Add searching for journal entries.
- #267: All models related to the Know Me app have creation and last-updated timestamps.
- #276: Return URLs in Know Me user list rather than only from the detail endpoint.
- Bug Fixes
- Miscellaneous
v0.7.0¶
Developed “Bookshelf” as a rework of the old “Gallery”.
- Breaking Changes
- Switched to third party account management package. This modified the endpoints used for email management, password resets, and registration. Also, the transition removed a lot of our account related models and modified their migrations. This means the existing database must be wiped and recreated.
- #209: Removed “emergency” related content.
- #214: Removed
is_defaultfield from profiles. - #239: Removed Layer integration. This means Layer authentication tokens can no longer be obtained from the API.
- Features
- Bug Fixes
- #224: Fix issue with incorrect filtering of list views.
- Miscellaneous
- #208: Switched to autogenerated documentation.
v0.6.0¶
Implement sharing of profiles.
- Features:
- #154: Allow profiles to be marked as private. Private profiles are not accessible by shared users unless they are explicitly granted access.
- Bug Fixes:
v0.5.3¶
Update dependency versions.
v0.5.0¶
This release was focused on renaming the components of a Know Me user’s profile. As a result of this renaming, this release will break all existing data related to Know Me. This change also caused several endpoints to be renamed. The most relevant issue here is #65.
/know-me/gallery-items/*to/know-me/media-resources/*/know-me/profiles/*to/know-me/users/*/know-me/rows/*to/know-me/topics/*
- Breaking Changes
- Features
- Bug Fixes
v0.4.0¶
- Breaking Changes
- Features
- Miscellaneous