Pulp

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