We’ve told you about a lot of cool stuff over the last few weeks, but nothing is as cool as this. We have made (almost) the entire API writable. That’s right, you can build apps to upload images, edit breweries and beers, add new content… Whatever you like. And the most important thing – you can always be sure that GOOD data gets into our system.
How does it work?
Each one of our main entities (beers, breweries, brewery locations, brewers guilds, and events) are all writable. That includes any of their sub-attributes like social media accounts, ingredients, or awards. When you send a request to write something to our database, the API automatically creates a change order and lets us know. Our team verifies the changes, presses a new fancy button, and your change is in the database.
For New Entities
When you add a new beer, brewery, brewery location, brewer’s guild, or event to the system, it is immediately added as part of our data set. It can be viewed, searched, edited, whatever. However, we set the status to “new_unverified”, which means as you are reading data from our API, you immediately know what you can and can not trust. It’s up to you, the developer, to handle this case but we wanted to make sure the data was available to you. Once our staff checks it out and verifies the information, we change the status to “verified.” This status marker is one you can trust, because our staff has made sure the data is accurate.
Editing Existing Entities
When you edit an existing beer, brewery, brewery location, brewers guild, or event, the change order is sent to us and that change is not visible in the API until we verify it. For example, if you make the call to our API which assigns a new twitter handle to Oscar Blues Brewing Company, we get a change order to add the account. Until we verify the change, the data DOES NOT show up in the API when you query the social media accounts for Oscar Blues. This way you can be sure that whatever data you read from the BreweryDB API has been curated by our staff, ensuring the highest quality data. We will also set the status to “update_pending” for the entity, so you know that your change has been received.
Deleting Entities
Deletion of existing entities works the same way editing does. If a brewery is no longer in existence or something is just wrong in our database, a request for deletion can be sent to us and we will process it accordingly. A status of “delete_pending” is then set for the entity so it is up to you, the developer, to display it or not.
Why This Is Awesome
This means that you can write apps that completely encompass the entirety of BreweryDB. Your users can immediately add beers, breweries, brewery locations, brewer’s guilds, and events with limited moderation. Changes to existing entities get approved by our staff, so you can trust our data. Also, any requests you make to the write methods do not count against your API request limit. It’s a great way to contribute back to the data that you use in your application!
What is Not Writable
Certain things are not yet writable. Endpoints such as category, styles, ingredient lists, etc. are not writable yet. If changes are needed to these lists (which usually do not need changing) we will have to administratively alter them. Let us know by sending an email to the BreweryDB Google Group and we will figure it out.
In Conclusion
We think this is the BIGGEST feature that we are offering with version 2 of the API. It gives everyone who uses the data an incredible, crowd-sourced opportunity to build our database. The more people who participate, the better and more complete the data will be. We at PintLabs are excited to see what you guys are building, so let us know what projects you are working on!