Here at Marqeta, we continually strive to improve our developer experience. Over the past few months, we have been rigorously working towards creating a single source of truth for our APIs, to be used by our engineering and documentation teams. As part of this initiative, we’re proud to share with you the beta version of our API definitions, which can be found at https://github.com/marqeta/marqeta-openapi!
What does this mean for you?
- Single source of truth: Build your SDKs and implement your product based on the same source we use to generate our public documentation and APIs. Working from a common source means fewer surprises for you as you develop, as well as increased consistency.
- OpenAPI 3.0: Our API definitions are now based on the OpenAPI 3.0 standard. Moving to OpenAPI 3.0 will enable you to use current OpenAPI 3.0 tools for your day-to-day development, including code generation and viewing documentation in your preferred tool.
- Beta: While we’ve put much effort into deriving our code and documentation from a single source of truth, work is still ongoing. We have already compiled a list of items we’d like to improve (see Known issues below), but there could also be other larger changes to our definitions such as how we approach versioning, and whether we provide our API definitions as a single file or as multiple files. Some of these changes will also depend on feedback we receive from you, our users.
Known issues
As with any beta release, improvements can and should be expected. We’ve decided to not wait until our current list of improvements is clear before giving you the first version to try out. We plan to address the following list of items, therefore there's no need to report these issues should you encounter them:
- Correct the inconsistent naming convention in schema names and tags
- Add some final endpoints that were excluded from the first release
- Remove redundant properties from schemas and operations
- Improve the ordering of properties for enhanced readability
- Introduce enumeration values where they make sense
- Increase reusability across the definitions
What’s next?
Other than addressing the known issues mentioned above, we welcome your feedback as you test and experiment with our definitions. In the future, these definitions will also serve as the basis for our new public SDKs, which we’re hopeful you’ll enjoy. Feel free to let us know which languages you would like us to support. We will have an open thread for discussion in the community where we welcome your input.
- Marqeta Developer Experience Team
Join our developer newsletter to hear about the latest updates.
