---
# System prepended metadata

title: mascot-core-api!
tags: [architecture, ' design']

---

---
title: mascot-core-api!
tags: architecture, design
---

# mascot-core-api
4th February 2022

---

Essence of an API: Turning traditional complexity into programatic simplicity

---

### Examples

![](https://i.imgur.com/pIqYncU.png)
![](https://i.imgur.com/FC2YH2h.png)

*Stripe's API journey: https://stripe.com/blog/payment-api-design*

Food for thought!
 - What use cases could people build using mascot-core? Shubham will show us a glimpse upnext!
 - If there’s an orchestrator which runs everyday and updates data in the warehouse - that orchestrator should be able to interface with mascot-core!
 - Resources vs Functionality!


---

### Building blocks
 - account
     - warehouse
     - database
 - entities
     - users
     - organizations
 - events
 - metrics
 - integrations

--- 

### Consumers

 - Application layer with people looking to get answers from the data
 - Data layer trying to build the right workflows with all the raw data

Our API should be able to support both of these, now and in the future

--- 

### The API

 - What do we have now?
     - `POST /pbf/connector`
     - `POST /signal/evaluate`
     - `POST /organization/signup`
     - `POST /organization/houseware_snowflake_setup`
     - `POST /organization/byow_snowflake_setup`

 - What we should probably be building!
     - users
         - `GET /user` with a payload: could be a count, list
         - `GET /user/metadata` — returns all schemas,all tables and all columns within it that talk about users as the central entity!
     - organizations
          - `GET /organization` with a payload: could be fetching details about a particular organization, fetching the list of orgs on your account
     - events
          - `GET /event` with a payload - could be a list, could be count of events by a certain aggregation, could be the entire event list for a particular user
          - `GET /event/metadata` — returns all schemas,all tables and all columns within it that talk about events as the central entity!
     - metrics
          - `GET /metric`
          - `POST /metric`
          - `PUT /metric`
     - integrations
          - `POST /integration/fivetran`
          - `POST /integration/stitch`
          - `DELETE /integration`
     - account
        - `POST /account`
        - `POST /account/user`
        - `POST /account/warehouse?type=snowflake`
        - `POST /account/database?type=postgres`

 - Updating tables & metadata about entities/metrics

     - `PUT /event/transformation` - with details on the formula/join/metric, target table
     - `PUT /user/tranformation` with details on the formula/join/metric, target table


---

### Documentation

 - To gear documentation towards how to use an API, rather than how it’s built.
 -  Build guides early on in the process — even for our first beta users. 
 -  It may not be perfect, but it’s a great start when first onboarding customers.

Exploring Gitbooks and Readme to maintain our documentation!

---

### Open Questions

 - Are we missing out on any core resource?
 - If a user wishes to play with the data - do we handle compute on the client - how heavy is the compute gonna be? Should we offload all data manipulations to queries?
 - How performant our APIs with warehouse gonna be? How would it differ b/w SF and BQ?

---

### Thank you! :sheep: 

