API Design for Save and Validation Scenarios

asharma377
Participant V

Hello,

I have an API where we want to save commercial breaks. There are also validations in terms of rules such as hour limit not breach, average duration with in limits etc.

Should such validations have a different endpoint such as POST commercialbreaks/validation and then we validate the same from UI

a. UI ->commercialbreaks/validation , if pass then UI hit commercialbreaks->POST /commercialbreaks.

b. or should we have a single endpoint i.e POST /commercialbreaks and then have /commercialbreaks/validation be called from inside inside this API.

Validation takes user input too for rules to validate against. We will have to pass the same whenever we hit POST /commercialbreaks if we go for b).

There is also a possibility that post validation, there is a delay in save and then by then some changes have happened in system so we may need revalidation again.

Which is a better design approach?

Also, we have a situation where Validation gives a message that it failed/passed and if user has the Override prvilige then he will be be able to override the validation and still be able to save the breaks. In this case should we have use the same endpoint POST /commercialbreaks with override flag =true/false. Please suggest.

0 1 911
1 REPLY 1

It's a good design question.

Apigee Edge is best used for API Management - management of the APIs your system exposes to external consumers. "Management" in this case, from the perspective of the API Gateway, includes things like authentication and authorization of the inbound calls, validation of the payloads of the the calls, signature validation or enforcement, quota or rate limit enforcement, analytics, and a few other things.

You're asking "should the UI be able to call an API endpoint like /commercialbreaks/validation ?"

And my response is: does the user experience require it?

Here's more:

I guess if you want to allow a client to save some information - you decribed commercial break information but it could be an entity in any domain. It could be a healthcare record, it could be a favorites list for a shopping app, it could be a configuration for a geoengineering monitoring device.

When saving the information, the client passes an entity id and a representation of the information to save. I imagine a RESTful API would look something like this

POST /commercialbreaks/01235

{ "start": "01:09:40", "duration" : 90, "media": "gcs://url-goes-here" }

...where 01235 is the unique identifier of the commercialbreak entity, and the payload includes the details. Surely it is much more complicated than that, but anyway the exact payload doesn't matter.

The SAVE operation needs to validate that information before saving.

This validation step is not optional. The save operation must explicitly or implicitly validate what is being saved. The save and the validation that it requires is done by the backend (or "upstream") if you like. Maybe that capability is implemented as a microservice and is hosted in a kubernetes cluster. Maybe it is a Google Cloud function. Maybe it is a large legacy monolith running on a VM. Or something else.It doesn't matter. The point is, that "validate-and-then-save" capability is upstream of Apigee Edge.

OK, so what about allowing the client (the UI) to specifically request a validation BEFORE asking to save the information? That seems like a reasonable thing to want to do, to support a User experience in which the UI gives adaptive feedback to the user based on what they are entering *right now* in the UI.

For example if the user has specified a commercial break duration that is too long given the other constraints that are in use, then the UI should flag that in red, before the user tries to save anything. The UI should just point out - hey this is too long!

To support that you'd need a validation endpoint as well. It might look like:

POST /commercialbreaks?validate
{ "start": "01:09:40", "duration" : 90, "media": "gcs://url-goes-here" }

And then Apigee Edge would manage that inbound request and pass it to the upstream endpoint which does only validation.

Some recommendations then:

  • Expose 2 endpoints as managed APIs: Save and Validate. Both will be invoked independently by the UI.
  • Do not require the UI to call "validate" before calling "save". The validate should be implicitly done by the save logic, behind the scenes. When the "save" implementation performs its validation, it need not invoke this through the Apigee-managed endpoint. Probably a better idea is to just allow the "save" logic to invoke the "validate" logic directly. (Maybe via an endpoint exposed directly by a microservices service)
  • Allow the UI to call "validate" as often as it likes, to support the user experience.

Also, we have a situation where Validation gives a message that it failed/passed and if user has the Override privilege then he will be be able to override the validation and still be able to save the breaks. In this case should we have use the same endpoint POST /commercialbreaks with override flag =true/false. Please suggest.

yes, that sounds right to me. I guess it would look something like this:

POST /commercialbreaks/01235?validate=false

{ "start": "01:09:40", "duration" : 90, "media": "gcs://url-goes-here" }