FOAM Developer Update — Version 1.0 API Release

Stabilizing the FOAM API and some Helpful UI Changes

FOAM Developer Portal homepage (https://f-o-a-m.github.io/foam.developer/)

Earlier last week we released a version of the FOAM map application that we’re proud to call our v1.0 stable release. What this means is that our API is now stable, and we will begin to place importance on enhancements and extensions that are non-breaking. This enables us to better support developers outside of the FOAM team who would like to integrate with our platform. We also released a few changes to how we present challenges to the user, see below for more details.

Developer Portal

Developer Portal Homepage

The FOAM Developer Portal is where developers should go to view API documentation, download JavaScript client libraries (available as an axios or angular library), propose enhancements, or raise issues for all things related to the developer experience with the FOAM map. The FOAM Discourse is still the best place to raise concerns relating to the community or web application (e.g. bugs, concerns).

Swagger Documentation

Interactive REST API documentation via swagger.

One of the most useful features of the developer portal is the swagger documentation. This allows you to query our REST API directly in the browser and view data models as well as examples. It’s also possible to take our swagger.json template file and generate a client SDK in several languages.

UI Changes

More Precise Challenge Info

Example of the new challenge card

In an effort to better explain the token related challenge data, we have expanded the challenge card with some useful information. You will now see:

The number of FOAM tokens available in the POI which are not locked in the challenge. The amount of the challenger’s FOAM tokens which were deposited and locked in the challenge. The total number of FOAM tokens to be shared between the voters on the winning side. The ratio of the amount of tokens that go to the winner of the challenge (POI owner or challenger) versus the number to be divided among the winning voters.

Throwing Salt in Your Cache

We’ve heard stories of users not being able to reveal their vote on account of having lost their commit salt (the data that enables you to commit a vote without declaring your choice). Since you’re required to provide this salt in order to have your vote counted, we decided that one way to help would be to cache the salt in your browser’s local storage.

The prompt before submitting the commit transaction.

Heres what this means for the user:

We will save the salt in your browser’s local storage under the FOAM map namespace. This means it will not be accessible to other sites, since no commonly used browser allows you to read or write from local storage on a different domain. When you go to reveal your vote, we will check local storage for your commit data and attempt to auto-populate the reveal form. No more checking for the salt in your filesystem or notepad on your computer. If we can’t find the stored commit for some reason — like you’ve deleted your browser history or have some restrictive browser settings — you will still have the option to fill out the reveal form by hand. We recommend still saving the commit info somewhere safe if it’s very important that your vote is counted. This is just one attempt to avoid a common problem, but saving the salt yourself is the only way to be absolutely sure you can reveal your vote regardless of what happens to your computer or browser.

Example card where salt was found and automatically loaded

Example card where salt was not found because browser history was cleared

Unseen Changes

PureScript Language Upgrade

One of the biggest unseen changes — changes not visible to the user — is that the FOAM map webapp has been upgraded to use the newest version of the PureScript Language version 0.12. This is a big update for us as it makes the application more efficient and more secure in its behavior. Big shout out to the PureScript core developers for their amazing work.