Define initial SeamBlueprint interface

[razor-x]

• src/lib/blueprint.ts

[razor-x]

Now that we have something to work with, we should define some common terminology, I've noticed that the Seam API has a few different kinds of nesting. Here are some key ideas and examples (and proposed terminology).

1. Let's define an endpoint as a true leaf node: This is an http path that you can send an HTTP request to. The endpoint for listing devices has the path /devices/list.
2. Define a route as a collection of endpoints. This is what we generate individual classes for, e.g., each of the files here is a route: /devices is a route that contains the /devices/list endpoint.
3. Define a namespace as a collection of routes. The ACS namespace has path /acs but contains no endpoints. Not every route has a namespace, so it might be better to attach the namespace to the route.
4. What about these special cases?
   • /devices/simulate: This is another route, but it happens to have a parent. We can say it's a subroute devices Category.
   • /devices/unmanaged: Similar to simulate, this is another subroute.
   • /locks: Route.

We have some related concepts:

• Resource: e.g., device, connect_webview, user_identity, acs_system. All resources have a corresponding top-level route (or route inside a top-level namespace like /acs.
• Sub-resource: identical to a resource, but has a corresponding nested route, e.g., enrollment_automation lives under /user_identities/enrollment_automations. I don't think we should treat subresources differently from resources. We can just track where their "home" is if that's useful.

[razor-x]

With the above, we might structure the blueprint like this to optimize for the SDK generation

interface Blueprint {
  routes: Route[]
}

interface Route {
  endpoints: Endpoint[]
  subroutes: Route[]
  name: string // Devices
  path: string // /devices
  namespace: Namespace | null // null for /devices in this case
}

interface Endpoint {
  name: string // List Devices
  path: string // /devices/list
}

interface Namespace {
  name: string // ACS
  path: string // /acs
}

[kainpets]

I've tried to implement those proposals here - LMK what you guys think - @andrii-balitskyi, @razor-x, @mastafit Left some comments for myself to easier wrap my head around what's what.

[kainpets]

Could Namespace implement Category mentioned here https://github.com/seamapi/blueprint/pull/6#discussion_r1648183658? Kinda makes sense to me

[razor-x]

I thought about that but I'm not sure if it works. Category is more of a conceptual group than a logical one. Is ACS, ACS User, and Device all categories? Only ACS has the special nesting.

[razor-x]

@kainpets Next thing we should focus on is Response and Resource. My thought initial thought is that the Seam API always returns complete resources, so something like this should work

interface Response {
  responseType: 'resource' | 'resource_list' | 'void'
  responseKey: string | null // access_codes
  resourceType: ResourceType | null // access_code
}

interface Blueprint {
  resources: Record<ResourceType, Resource>
  ...
}

interface Resource {
  resourceType: ResourceType
  properties: Property[]
}

interface Property {
  name: string
  type: 'string' | 'enum' | 'record' | 'list' | 'object' // unsure about this one
  properties: Property[] | null // only defined if type is 'object'
}

Ideally ResourceType can be self consistent, so blueprint.resources[response.resourceType] is always NonNull<Resource>. Can we do this with a generic or inferred type form the openapi spec?