search

LiveRamp / reslang

A language for describing resource-oriented APIs & turning them into Swagger or resource diagrams. Oriented around the concepts we want to expose in the APIs.
Apache License 2.0
23 stars 7 forks source link

support for non-public attributes #133

Open j-q-arnold opened 3 years ago

j-q-arnold commented 3 years ago

We are building a data model based on our reslang. In some cases, the data model for an object needs attributes that we don't want external clients to access through the API. The attributes might be used for on-call or internal support. They seem important to the model, but we don't have a way to include them in reslang without exposing them publicly.

Suggest a private modifier to document an attribute in the data model (reslang) without affecting the public API.

This brief description lacks sufficient nuance. For example, we might want access to the data controlled by client permissions or identity. For example, if the client is the on-call person or technical services, we might want to enable access. An external customer might have no access at all.

Need some work to determine the actual enhancement here, but happy to discuss further.

sagarrbatchu commented 2 years ago

@j-q-arnold Hi Jim, could you give us a few more details on the use case for non public attributes ?

j-q-arnold commented 2 years ago

Reply to @sagarrbatchu : Discussion with @bvivio :

I think there are still some things that are relevant:

  • In our API we don't expose the batches that we have to perform behind the scenes when processing groups of segments (for instance, we have to batch by audience based on current limitations of the system). But as an OC task it might be super useful to be able to backfill a specific batch (similar to an SSA backfill we sometimes perform today). We wouldn't want to publicly expose the resources we use to control the batching behind the scenes (e.g. DataPool, SegmentDeliveryDigest), but those resources are useful to operate on as an OC.
  • We currently expose Refresher Service Request IDs in our interface, but it really has no purpose for clients. It's basically only used so that our Segment Delivery UI and OW Dashboard can be linked together conveniently, and for convenience for OC engineers so we don't need to run manual DB queries to connect a SegemntDeliveryAttempt to a specific Refresher request.

With CAC, we can have strict permissioning on resources so that only our internal service accounts can interact with certain resources, which is nice. But the resources would still be part of the public-facing API and so clients could see those endpoints and the documentation. They just would get back FORBIDDEN errors when trying to actual call the endpoints.

I'm not sure if there is actually a good solution for some sort of private modifier...like would there be separate client/server generated code/stubs for private and public clients? It might be the case that we just want to build in tooling that is not part of the public-facing API to do common OC actions in a slightly clunkier way (either building some sort of internal facing "oc operations" service like OW Service, or just by building scripts/crons/apps to perform certain OC operations directly via DB updates, Pub/Sub operations, etc.