OpenAPI Specification (OAS) support

[MajorLift]

New Feature / Enhancement Checklist

• [x] I am not disclosing a vulnerability.
• [x] I am not just asking a question.
• [x] I have searched through existing issues.

Current Limitation

There is no support for the OpenAPI Specification (OAS) standard.

Feature / Enhancement Description

1. Serialization of Parse Server instances into OpenAPI documents

• Many major services including Github, Twitter etc. publish API details in OAS 3.1 format.
• "An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases."
• OpenAPI supports specification of full range of REST API functionality including multiple servers/endpoints/methods/headers/parameters, request/response formats, authorization/authentication details, callbacks/webhooks etc.

  2. Code generation feature for deserializing OpenAPI definitions into fully functional Parse Server instances.

• Would enable a Infrastructure as Code (IaC) workflow (e.g. Docker Compose, Ansible, Terraform, ...) where the developer only needs to write out a REST API as a declarative configuration file, and Parse Server automatically handles the implementation of the interface.

Example Use Case

Detailed in above section.

Alternatives / Workarounds

Unaware of any other than manually transcribing OAS documents into Parse Server configuration.

3rd Party References

• https://github.com/openapitools/openapi-generator/
  • Generates clients and server stubs in multiple languages/frameworks
• https://openapi.tools/#server
  • List of server generators. Only one supports OAS 3.1 so far.
• https://github.com/nestjs/swagger
  • nest.js has a serialization module for an outdated version of OAS.

Remarks

• I would be willing to make contributions on this feature if there is any interest.
• I'm not completely familiar with this amazing project yet, so if I'm somehow way off mark with this, please don't hesitate to point it out.

[parse-github-assistant[bot]]

Thanks for opening this issue!

• 🎉 We are excited about your ideas for improvement!

[mtrezza]

It would be interesting to find an adapter-like concept to add such APIs. We currently have a GraphQL implementation which was implemented as a fixed part of parse server, but over time it became clear that such a deep implementation poses unnecessary challenges for deployments that do not make use of that API. And when another "standard" comes along like the OAS, then it cannot be easily swapped.

So the first step for this feature could be a design for how such an adapter-like API interface could look like. Then, gradually one could start to implement the API, until it dies off organically, like other standards have.

[MajorLift]

Thank you for the feedback @mtrezza ! If I'm understanding correctly, you're suggesting first writing a generic interface based on parse server's current feature set, and then writing a shim/compatibility layer tailored to the current version of OAS on top of that?

That does seem to be a lot more maintainable and flexible way of going about this. Being able to insulate parse server's adapter interface from minor changes in the standard would be a valuable feature.

It also seems in that case that I won't be able to make any contributions on my own until I'm much more familiar with the codebase. I'll be onboarding myself, but in the meantime I'll welcome any guidance, ideas, or general comments from the team.

[mtrezza]

If I'm understanding correctly, you're suggesting first writing a generic interface based on parse server's current feature set

Maybe that generic interface does already exist - we could use the REST API which always has the complete set of features, because it's the basis for every Parse client SDK. It's also well documented. REST is probably the most basic form of API that has been around for long and will stay with us for the foreseeable future. Then all that's needed is:

• a) writing the adapter mechanism so that one can optionally plug in the OAS API adapter, or GraphQL API adapter (which is currently hard coded into Parse Server, but could/should move then out of the core codebase), or any other future API adapter
• b) writing the OAS adapter itself

I'll be onboarding myself, but in the meantime I'll welcome any guidance, ideas, or general comments from the team.

You could take a look at the various existing adapters in Parse Server (database, etc) to get inspiration for the API adapter mechanism. At the same time you could write the OAS adapter with just a few basic features (e.g. create & delete object), as you will probably get more insight as you so along. Then you could add a few more basic features and we can release it for developers to try out, while you can continue to make more features available in the OAS adapter and hopefully others will contribute and maybe do a few implementations as well.

[MajorLift]

You could take a look at the various existing adapters in Parse Server (database, etc) to get inspiration for the API adapter mechanism. At the same time you could write the OAS adapter with just a few basic features (e.g. create & delete object)

These seem like excellent starting points. OAS is a standard specifically for describing REST APIs, so implementing basic CRUD functionality first and building on that seems like a good approach. I'll look into the existing adapters in the codebase and see if I can whip something up.

[dani69654]

Following.

[mtrezza]

@MajorLift Nice, I'll add a bounty to this, as I think it would be quite a great extension to make Parse Server more versatile and interoperable. And it could lighten the footprint of Parse Server if it allows us to move GraphQL out of the core codebase.

[mtrezza]

What would a rough roadmap look like for this issue and where would the swagger file fit into it?

[MajorLift]

@mtrezza Sorry for the late response! I'm still interested in working on this, but I've been onboarding at a new position and just haven't had the time. I'll let you know once I'm more available.

I think starting with implementing serialization of a parse server instance into an openapi document (i.e. swagger file) preferrably using the existing API adapters might make sense, as it will have deterministic output, and the modules written in the process could be built upon to make the adapter more extensible/standard-agnostic, which would lay the groundwork for implementing the deserialization feature.