search

dropbox / nsot

Network Source of Truth is an open source IPAM and network inventory database
https://nsot.readthedocs.io
Other
400 stars 66 forks source link

Update REST API schema to use open standards #274

Open jathanism opened 7 years ago

jathanism commented 7 years ago

The release of Django REST Framework 3.5.x introduced support for multiple open API standards including OpenAPI/Swagger and CoreAPI.

See: http://www.django-rest-framework.org/api-guide/schemas/

Swagger, especially, facilitates the ability to do client code generation. This can lay the groundwork for simplifying the ability to create NSoT clients in other languages. At the very least, the new schema definitions are more robust and will provide a means for better programmatic enumeration of API endpoints for clients.

jathanism commented 7 years ago

It appears we may want to wait until DRF 3.6.4 which should be adding support for the generation of response schemas. See: https://github.com/encode/django-rest-framework/issues/4502

jathanism commented 7 years ago

DRF 3.6.4 is out!

For additional context, one of the primary use-cases for a standardized schema is generating a Golang client using go-swagger.

I've started experimenting with using a project called drf_openapi which allows for explicitly setting request AND response serializers to define the schemas for each. This is necessary for any client code generation for strongly-typed languages (such as Go).

tyler-8 commented 6 years ago

drf_openapi has been deprecated in favor of https://github.com/axnsan12/drf-yasg/

jathanism commented 6 years ago

Ah yes. I knew that just didn't update the ticket. Thank you!