Create a plan for the REST API in 3.0
There seems to be agreement on using the django rest framework. These questions need to be answered:
- Which version and why?
- How do we communicate to developers how to document the REST API?
- How will docs get built and distributed?
- How will search work, and how will we determine which fields to make searchable on each model?
- What is the best option for auto-generating client libraries?
Below are notes from the team:
Q: Will we definitely use django-rest-framework (DRF)? What version? Yes. The latest version of DRF supports Django 1.8+, is not packaged in Fedora, and is currently at major version 3 (3.4.0). This is the version we should target. Q: How will docs be generated? Docs for API endpoints are generated using the docstring of the View class that provides that endpoint. Visiting the endpoint using a browser will render the docs, and DRF also works with swagger and other API docs generation tools to put all the docs in a single browseable place. http://www.django-rest-framework.org/topics/documenting-your-api/ Q: How will search work? How will we ensure we meet user needs? Investigation is still needed here. Assuming that we don't really need full-blown "full text" search with stemming features, we can likely get everything we need using the django-filter plugin, which DRF supports. https://django-filter.readthedocs.io/en/latest/ http://www.django-rest-framework.org/api-guide/filtering/#djangofilterbackend Q: Can we auto-generate a client library or similar? This is a major feature that came with DRF 3.4: http://www.django-rest-framework.org/topics/3.4-announcement/#schemas-client-libraries http://www.django-rest-framework.org/topics/api-clients/#client-side-core-api