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
- JWT MUST have verified access to an owning [Scopable] entity (access level never narrows)
-
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
- you must have a verified permission grant on a hierarchal scope
-
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
- in order to explicitly assign any item as a scope to an entity you must have a verified
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