What is Open*?
Open* (pronounced “Open Star”) is an open-sourced project that we have undertaken to aid developers in consuming APIs that they would normally have a difficult time in using. We do this by utilizing the OpenAPI/Swagger standard and integration testing to product reliable OpenAPI specs and NuGet packages for the community. Our goal is to create a testable OpenAPI specification file that can used by any developer in conjunction with a client code generator to create all the code that is required to interact with an API including security requirements, URLs, strongly typed requests and responses, and documentation.
We are continuously working on building out our Open* library. You can find a link to them below. Not all Open* projects are owned by us, but we are the main contributors to the projects. Given that we do consulting as well, we try to get our customers involved in the project. We also reach out and encourage other API developers to contribute.
Why OpenAPI?
If you do not know about OpenAPI, I highly recommend you read their FAQ to get a quick rundown of where they came from and what they do. To summarize, OpenAPI is an API documentation standard that is designed to be both human and computer readable. This is a standard that can be generated by the application itself or manually created. Being that it can be read by a computer as a simple JSON or YAML file allows for clever developers to create programming code directly from the document. When a well formed OpenAPI spec is available, developers no longer have to worry about the nuances of typos in their API calls or wondering how to manage exceptions from the API among many other things.
Why Use Open*?
In developing applications and data pipes over the years, we have had to deal with API providers whose documentation is incomplete, inaccurate, or misleading. We have to consume these APIs on multiple projects where we would have to manually keep paths and objects up to date with the various releases. Incomplete documentation may have paths, but incomplete results specified. Date formats may be hard to implement in a given language. Endpoints may not be listed at all. Error codes may not be listed. Or the data that is returned may not always be what it is documented to be. This is where Open* comes in.
For an Open* project, we strive to provide the following:
- A way to capture all the endpoints via existing documentation. This may be a simple scrape of a website to create a list of every path that already detailed.
- A strongly-typed data model for the request and response objects and parameters.
- All response types/objects for every endpoint.
- A simple naming convention for client code generators to use when naming methods and functions in your applications.
- Comprehensive error handling.
- And descriptions and notes from the existing documentation is copied into the new spec.
- A NuGet package for .NET developers to easily consume the API if any extra features are required such as rate limiting or extra data validation.
Eat You Own Dogfood
Creating documentation that is OpenAPI compliant is one thing. It is another to use it solely when interfacing with an API. Our data pipe tools only use code that is generated from these specifications. That way, you can be sure that the documents we build are complete and easy to work with.
I encourage all developers to try this path. If your organization uses APIs that are consumed internally or externally, use a client code generator in conjunction with an OpenAPI spec to interface with your own APIs. For one, it will bring any potential documentation issues to light quickly and force development teams to have complete documentation. Also, you now, no longer have to manage client code explicitly in your websites or other consuming applications. If you add a new endpoint or a new version, a simple rebuild/reprocess by your code generator will automatically add the new features to your application. Hard to argue with the time savings once you get it right.
OpenAPI Client Code Generators
Not sure what a code generator is or what to use? Here are some links to various tools for specific languages that can get you pointed in the right direction. These are not endorsed, just tools that we use. If none of these fit the bill, a search for your programming language and “openapi client generator” will uncover tools and processes that you can use.