Ever since we released the new automatic documentation functionality for Socrata APIs (often called “API Foundry”), the most popular request by far has been the introduction of API documentation for private datasets. We’ve also noticed an exciting trend of our customers using private APIs as a foundation to build web apps and services upon.
So, we’re very proud to announce the availability of automatic API documentation for private datasets! When you visit the API documentation for a private dataset, you’ll receive a notice prompting you to authenticate to allow the documentation generation tool temporary access to your dataset:
Once you’ve done so, the documentation tool will automatically generate documentation for your private dataset’s API, just like you’re familiar with for public datasets.
Security is of critical importance to us, so we didn’t cut any corners when developing this new feature. All of its code is Open Source and open to review, and we encourage you to read on if you’d like to learn some of the more technical details on how it works.
When you visit the API documentation for a private dataset, the following things happen:
403 Unauthenticatederror response to let us know that the dataset is private. We detect that and prompt you to log in to view your API documentation.
When you’re done, you can either click the “Log out” link or close your browser, and you’ll automatically be logged out.
A number of very deliberate steps were taken to ensure that this could all be done securely:
GETrequests are proxied and the proxy can never be used to modify data or metadata
All of the code is also available in Github for your review and feedback: