Customer specific behevior. Bad question or poor design

[Jacek M]

Hi,

I am currently working on Web API for our old core system. We have a couple of problems with it as usually, however  one problem bother me for a while.

Lets say we have one resources representation like this:

{

  "bars": [

    {

      "name": "bar1",

      "value": "foo"

    },

    {

      "name": "bar2",

      "value": "ola"

    }

  ]

}

We have also defined possible list of all object names. Now every customer can defined its one mandatory set from this list, however this change need new agreement and end up with new PROD update. 

Problem:

If one customer request for mandatory fields change, no matter what it can break his clients (web apps, mobiles,) so we probably need to create new API version.

But it will be very irresponsible  in front of other customers.

 

Some solution can be let say, bars versioning per customer, however i am feeling that it is strange when we want to from one site expose one common API from another have some behaviors which are very customer specific.

Can you share your thought about it?

[Jørn Wildt]

> Some solution can be let say, bars versioning per customer, however i am feeling that it is strange when we want to from one site expose one common API from another have some behaviors which are very customer specific

Well, you can't really expose *one* API when each and every customer has its own custom business rules?

I would suggest you assign each client (web app, mobile etc.) its own client ID (as in OAuth2) and associate the client ID with the customer. Then you can "version" (or rather "customize") the API to match each customer's requirements.

In a later version you can expose the business rules (mandatory field set) as a separate "meta" resource that the clients can consume in order to align their view of the rules with the server's view.

/Jørn

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Jacek M]

Hi,

thanks for you replay. Obviously we want to authenticate user, so we can recognize from let say client and address proper set of rules.

Basing on that and versioning  we can some how solve this particular issue. By the way by versioning i mean something like this:

{

  "bars":{

  "version": "1.0",

  "items": [

      {

        "name": "bar1",

        "value": "foo"

      },

      {

        "name": "bar2",

        "value": "ola"

      }

  ]

}

}

However I am not convince to this solution because,  this version is per customer. For customer A version 1.0 is not equal version 1.0 for customer B.

Maybe it will be better to limit validation to if bar collection exist and create new one no matter what set of items provides. But still customers clients have to some how have possibility to "check" against their own rules.

Hope this more clear right now. 

[Johan Groenen]

You can use the Accept header for the request and the Content-type header for the response or something.

Accept: application/vnd.<yourapiname>[.customer].bars+json

Content-type: application/vnd.<yourapiname>[.customer].bars+json

But I think you are entering a world of pain...

[Jacek M]

Hi,

i see what you mean but i don't think it changes much. From technical point of view we can just end up with version number because we know  from which customer/client request come and we can address proper set of rules.

I was thinking about more drastic solutions:

1. Not validate bar collection, let api create a resource, and if internal system return error, return to customer that business process has failed. Has it have any sense?

2. Create common internal API and a lot of tiny web services per customer, which can theoretically works independently .

3. Or maybe changing rules by customer , which can obviously break his clients should not be consider like a breaking change. He want to do that it is his risk.

What you think about that. Which sounds less crazy or not crazy at all ?.

[Jacek M]

Hi,

i see what you mean but i don't think it changes much. From technical point of view we can just end up with version number because we know  from which customer/client request come and we can address proper set of rules.

I was thinking about more drastic solutions:

1. Not validate bar collection, let api create a resource, and if internal system return error, return to customer that business process has failed. Has it have any sense?

2. Create common internal API and a lot of tiny web services per customer, which can theoretically works independently .

3. Or maybe changing rules by customer , which can obviously break his clients should not be consider like a breaking change. He want to do that it is his risk.

What you think about that. Which sounds less crazy or not crazy at all ?.

On Saturday, January 24, 2015 at 3:59:48 PM UTC+1, Johan Groenen wrote:

[Manu Whig]

Personally, I think this is a customer application level concern instead of service API level. The service should define minimal required attributes for each resource. Attributes that are necessary for resource identification and possibly for authorization checks. Beyond those, all other attributes should be optional and the client application can then decide to add additional restrictions.

This keeps the service layer clean and gives maximum flexibility to the clients to define their own business case, without having to create a version-per-customer service. API versioning, if needed, should be driven by the service layer needs.

If you absolutely can't do the above and have to do customization on a per customer basis, I would rather go with your #3 option and provide the customer to define custom validation rules for each resource they want to customize. Then based on the customer's app-key (or some such key that uniquely identifies the customer), you can check if there are custom validation rules, load and execute them against the resource being acted upon. 

[Jacek M]

Hi Manu,

 

first of all sorry for not responding for a while I was out of civilization for a last two weeks.

 

Regarding to your answer. I think I agree with you, it has a big sense for me. The problem is either  is just so complicated in my head or it is really complicated :). I think it is worth to note that this API will not be the first company product. A lot of more customer application exist right now e.g. web product specific web app, some back office system for manage this products and so on. Big problem is that customer of such a app is sometimes also a owner of available products. This is way they don't want to repeated product rules all the time and expect for  us to validate message against their own rules.

 

The only reasonable solution which comes to my head right now is to introduce some how to customers two roles: API client and product owners - not related to API. In other words create boundary between "what happen in API" and in rest of system and not related those two thing even if they named the same. If we will do that we will have just product specific behaviour even if in many cases it will be one to one relation.

 

Sound reasonable for you?