CleanAppAPI (web2 dependencies)

CleanApp
CleanApp Report
Published in
6 min readDec 6, 2022

We’ve been working for years to build a blockchain-native dApp that handles large-scale incentivized CleanApp (1) reporting, (2) analytics, and (3) remediation. Our initial hope was for every component of the stack to be crypto/w3/blockchain-native. But our smarter blockchain peers have explained that, at this stage of blockchain’s development, that’s an unrealistic expectation.

So until the blockchain scaling stack matures further, we‘re building a hybrid dapp that strives to use w2 & w3 best practices in tandem. If you want to learn more about the hybrid dapp approach, we encourage you to read Vitalik Buterin’s recent article:

Building Hybrid w2w3 API

An API (Application Programming Interface) is a set of rules and protocols that allow different software applications to communicate with each other. APIs define how two or more applications can interact with each other, allowing them to exchange data and information. APIs are often used to provide a consistent and predictable interface to a web service or other functionalities, making it easier for developers to build applications that can access and use those services. APIs can be public, meaning they are available to anyone who wants to use them, or private, meaning they are only available to a specific group of users or applications.

CleanAppAPI

A public CleanAppAPI is a core component of the stack.

Our main design principles are utility (usefulness) and privacy. In practice, this is a very difficult tradeoff to navigate for a protocol that uses human-generated geotagged images to crowdsource the actionable data, but at the same time MUST protect these same humans from potential recrimination for generating what often amount to whistleblower complaints. Objectives:

  • we need the CleanApp Reports dataset to be publicly accessible, but not identify individual CleanAppers (to preserve privacy);
  • maximize CleanApp report generation (because more reports → more actionable data) from other apps, but minimize spam from bot operators that may want to game the protocol or run a DDoS attack;
  • minimize reliance on w2 dependencies that would complicate migration to blockchain-native infrastructure (dCloud versus w2Cloud), as blockchain infra matures, but use off-the-shelf tooling and best practices to launch and operate a scalable protocol;
  • there’s lots more in the documentation.

Key point: we need your help to design it to fulfill the objectives of utility + privacy.

Sample w2 API Flow & Dependencies

To start, we’ll share sample code of what a typical Web2 API flow looks like and flag some dependencies (eg, Apigee/Google middleware). To minimize reliance on these dependencies, what would you suggest are better and more scalable alternatives?

// Import the necessary modules and libraries
const express = require('express');
const Apigee = require('apigee-access');
const bodyParser = require('body-parser');

// Create a new Express app
const app = express();

// Use the Apigee middleware to validate API keys and JWT tokens
app.use(Apigee.middleware({
orgName: 'my-organization',
appName: 'my-app',
}));

// Use the body parser middleware to parse JSON bodies in the request
app.use(bodyParser.json());

// Define a route for creating a new user
app.post('/users', (req, res) => {
// Retrieve the user data from the request body
const { name, email, password } = req.body;

// Create a new user in the database using the provided data
const user = createUser(name, email, password);

// Return the created user
res.json(user);
});

// Define a route for retrieving a user by their ID
app.get('/users/:id', (req, res) => {
// Retrieve the user ID from the request parameters
const { id } = req.params;

// Retrieve the user from the database using the provided ID
const user = getUser(id);

// Return the retrieved user
res.json(user);
});

// Define a route for updating an existing user
app.put('/users/:id', (req, res) => {
// Retrieve the user ID from the request parameters
const { id } = req.params;

// Retrieve the updated user data from the request body
const { name, email, password } = req.body;

// Update the user in the database using the provided data
const user = updateUser(id, name, email, password);

// Return the updated user
res.json(user);
});

// Define a route for deleting an existing user
app.delete('/users/:id', (req, res) => {
// Retrieve the user ID from the request parameters
const { id } = req.params;

// Delete the user from the database using the provided ID
deleteUser(id);

// Return a success message
res.send('User successfully deleted');
});

// Start the Express app
app.listen(3000, () => {
console.log('CleanApp API listening on port 3000');
});

In the sample code above, access to the CleanApp API is controlled by the Apigee middleware. The middleware is configured to use the my-organization and my-app values for the orgName and appName options, respectively. This means that only users who have an API key associated with the my-organization (eg, CleanAppDAO) and the my-app (eg, CleanApp) will be able to access the API. Additionally, the middleware is configured to validate JWT tokens for each request. This means that only users who have a valid JWT token issued by my-organization will be able to access the API, even if they have a valid API key. This allows for more fine-grained control over who can access the API and what resources they can access.

A JWT token is a JSON Web Token, which is a type of access token that is commonly used in the context of OAuth2, an open standard for authorization. A JWT token is a signed and encoded JSON object that contains information about the authenticated user and the permissions they have. When a user authenticates with the CleanApp API, the API issues a JWT token to the user. The user can then include this token in subsequent requests to the API, and the API will use the token to verify the user’s identity and determine what actions they are allowed to perform. This allows the API to enforce access control and prevent unauthorized access to its resources.

Apigee v. OpenAI

There are several advantages to using the Apigee approach outlined in the sample code above over using OpenAPI:

  • Apigee provides a flexible middleware layer that can be easily integrated into an Express app. This middleware provides a number of features and capabilities, such as API key and JWT token validation, that are not available in OpenAPI;
  • Apigee allows for fine-grained control over who can access the API and what resources they can access. This is especially useful when building APIs that are intended for use by multiple organizations or applications, as it allows you to control access on a per-organization or per-application basis;
  • Apigee provides a number of additional features and capabilities, such as analytics, traffic management, and developer portal, that can be useful when building and managing APIs. These features are not available in OpenAPI, so we would have to use additional tools and services to provide similar functionality.

So we have a classic tradeoff: on the one hand, the simplicity of open source OpenAPI for define and documenting APIs; on the other hand, the convenience of an enterprise-grade web2 solution for actually deploying and managing the CleanAppAPI(s).

Questions:

  • What’s the best way to securely automate the issuance of CleanApp JWTs, but minimize spambots?
  • To maximize reports, minimize spam, we can imagine a public pull, private push model (anyone can fetch data, but only authenticated bots can post data), but what’s the best way to monitor push-bot activity to revoke API access?
  • What are other tradeoff factors in Apigee v. OpenAPI consideration?

How Can I Help?

  • please share your experience with building hybrid w2w3 APIs by replying below & please help us build out our open-source codebase.

--

--

CleanApp
CleanApp Report

global coordination game for waste/hazard mapping (www.cleanapp.io) ::: jurisdiction mapping ::: no token yet, but launching research token soon 💚🌱