@flatfile/resources

Utilities for working with API resources

Flow of Fetching inforamtion

• Repository: Generates queries only, produces: Collection, Model, Primitive (count, etc)
• Service: Computes, combines, and manipulates data from or into the Repository
  • Response<Serializable>
  • Response<Collection<Serializable>>
  • Response
• Controller

ResourceCollection implements Scoped, Paginated

Scoped -> applyVerifiedScopes() Filterable -> applyFilter() Paginated -> paginate() -> paginationSummary() Response -> -> data() -> meta() -> error() Serializable -> toAPI(): ApiResponse<T|T[]> Request -> Authentication -> Authorization -> Payload -> Arguments CreateRequest extends Request -> Validation -> toModel() CreateResponse -> 201 Created -> Entity

Engine -> Driver

Example: -> upload a file -> POST to Controller -> // do stuff with binary file -> driver(drive).store() => // path -> service.createFile(req: CreateRequest): CreateResponse -> repository.insertFile({ file }) <- Response.toAPI()

Filterable

• show me files uploaded by me
• show me files uploaded to the primary space
• show me files with an extracted workbook
• show me files that have been uploaded to this workbook

Access in a collection must be a queryable constraint - ID piles are an ANTIPATTERN

• the service must know the different ways it may be considered in an access matrix

• the following types of constraints must be supported by all

• SCOPE & PERMISSIONS

  • JWT MUST have verified access to an owning [Scopable] entity (access level never narrows)
    • workbook: owned by environment, owned by space, authored by user
  • JWT MAY be granted explicit access to a resource in a way that supercedes all scopes
    • file: you have been granted write access to this file

• PERMISSIONS

  • you must have a verified permission grant on a hierarchal scope
    • you must always verify your identity and your permissions on at least one hierarchal scope in order to access the data
    • permissions may not narrow, this ensures that any permission granted on a parent is true of all its children

• ASSIGNING SCOPABLE ENTITIES

  • in order to explicitly assign any item as a scope to an entity you must have a verified read grant of that entity
  • when assigning a scope to any entity, all of that entities parents are implicitly assigned
    • this requires a tree-traversal query on scopes

scope	file_id
us0_sp_8y498h	us0_fi_8h4uhs
us0_wb_892hsl	us0_fi_8h4uhs

JWT

grant us0_sp_8y498h admin

API

drill us0_wb_892hsl