Linter
OpenAPI Editor

Publish Your Open Data in Less Than 10 Minutes

Including a free, advanced API and interactive documentation

 

TL;DR: Upload you data to GitHub and share the free GitRows API url to make it accessible for anyone. Add an OpenAPI document with GitRows’ online editor and link to the interactive documentation. Congratulations, you published Open Data in less than 10 minutes.

 

Have you ever thought about publishing open data but thought it was too complicated? Worry not, with GitRows it becomes easy as 1-2-3 and its completely free. No need to install any additional apps or whole platforms.

1. Upload your data to GitHub

You can skip this step if your already using GitHub: It’s widely used not only by developers for storing their code and collaborating on data. One of the main features of Git, the underlying open source system, is versioning. In a nutshell: You can always recover your code or data if something goes wrong - this is very handy for data management as you never need to think about backups again.

In the end you should see something like:

2. Your API is already there

One of the most important features of (and the main reason I wrote it) GitRows is the API Interface it provides to all public data files in .csv and .json format. An Automated Programming Interface (API) allows apps and other services to consume your data over the internet and is key to the Open in Open Data. The API url is always in the format:

https://api.gitrows.com/@namespace/owner/repository/path/to/file(.json|.csv)

where @namespace is either @github or @gitlab (the latter with experimental support)

You can easily convert any file url or check your API Path with the Linter and Converter Tool:

You can query the API with several filters including comparison operators (eg. greater as or not) making it suitable for most use cases where people would consume the data you are providing. Find out more about the available filters in the docs.

3. Create an OpenAPI definition

The OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. Basically it allows humans and machines alike to understand, what the API is capable of and what data it delivers. An OpenAPI definition can 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.

GitRows’ OpenAPI editor is probably the easiest way to create such a definition document. Head over to https://gitrows.com/openapi and enter the GitRows API Path you got from the linter tool in Step 2:

GitRows creates a basic definition you can now complete with a title, short description, your contact data etc.:

Once you are ready you can proceed to publish the API definition to your GitHub repository. You can do this from the editor. Click on “Continue with GitHub” and authorize GitRows for API access to your GitHub repository. If you prefer you can download the definition file from the Editor > Preview instead and manually upload it to the repository you host your data in.

Once the file is committed to GitHub you can use GitRows’ SwaggerUI to display an interactive documentation for your file. Just click on “Open in Swagger”:

You can share the link to the documentation on your Website, in the repository’s Readme file or any other place you want your data to be made discoverable. The editor shows the links for easy access after the OpenAPI definition was added to GitHub:

As a general principle the link structure is always:

https://swagger.gitrows.com/@namespace/owner/repository/path/to/filename.openapi.yaml

What’s next?

But you don’t have to stop here. You can use the file with a number of documentation or API test and development tools. Have you build something with GitRows OpenAPI? Why not share with us: blog@gitrows.com