5 ms·

>you can make as many changes to your service as you want without any coordination. I'm really not sure that's true. If I change my classifier endpoint, even w

by IanCal 11y ago

>you can make as many changes to your service as you want without any coordination. I'm really not sure that's true. If I change my classifier endpoint, even with the same API it's important people know that they might get different results for the same input. It might be really quite important for peoples analysis. Their system might not fall over, but that doesn't mean I don't need to coordinate with them. Perhaps I'm missing something in what you're describing though.

jedberg 11y ago
I would say changing the resulting data in a meaningful way is still changing the API. The API contract is not only the verbs that they can use but the nouns that you send back.
- IanCal 11y ago
  Well, if all you were saying is that given the exact same requests, the exact same responses come back then you don't have to co-ordinate changes, then I'd agree. I'm not sure that's a particularly controversial point. Although that does involve knowing your responses are identical. If my results are different at all I would need to notify people downstream.
  - deathanatos 11y ago
    I've found it's a mix between the two extremes. Obviously, I can't start suddenly returning XML instead of JSON, because "I feel like it and it's cool"; it breaks everyone horribly, so that needs to be version 2. But if you insist on upping the version effectively any time you do, you're essentially saying that any side-effect (not just output) visible can't be fixed, except by duplicating the API and creating a new version, fixing it there, and moving the callers over (if you can — this, I've found is the hardest part[1]). Often, these are things that I feel like the spec is supposed to hash out: what is it supposed to do. If it strays from the spec, that doesn't necessarily require a new version number, especially if it doesn't break things. However, it has been my experience in that even the most benign changes will break things; you've got to be able to evaluate and figure out who is not following spec, and sometimes, how bad is the effect of the change if the clients didn't like it. (Is it so bad that, even though it's to spec, I should roll back? Or should the client fix the buggy behavior they've been depending on, and we can carry on in the meantime?) [1]: Mobile clients are out there. Unlike a web page, there's no way to edit/update them — you can push a new version, but will the users upgrade? At some point, you have to cut them, I suppose, but after how long? 6 months? <2% share among the user base? the active user base? What's an active user? (and now higher ups are involved, and you're in meetings…) [also]: https://xkcd.com/1172/ https://xkcd.com/1172/
  - jedberg 11y ago
    > If my results are different at all I would need to notify people downstream. Presumably your API says what types of data the caller should expect. As long as you don't change that, they should be able to deal with the response changing. But really it's more about the fact that if you have a single monolith, if you want to make a change, you have to coordinate with everyone at the company, whereas if you have microservices, you only have to coordinate with those who are affected by the change.
    - IanCal 11y ago
      > Presumably your API says what types of data the caller should expect. As long as you don't change that, they should be able to deal with the response changing. The point I wanted to get across was that although a client won't break, I'd still want to talk to those pulling data from the system. I was disagreeing with the statement "you can make as many changes to your service as you want without any coordination." > But really it's more about the fact that if you have a single monolith, if you want to make a change, you have to coordinate with everyone at the company, whereas if you have microservices, you only have to coordinate with those who are affected by the change. Yes, it does lower the hurdles to getting something out.

by IanCal 11y ago

jedberg 11y ago

I would say changing the resulting data in a meaningful way is still changing the API. The API contract is not only the verbs that they can use but the nouns that you send back.

IanCal 11y ago
Well, if all you were saying is that given the exact same requests, the exact same responses come back then you don't have to co-ordinate changes, then I'd agree. I'm not sure that's a particularly controversial point. Although that does involve knowing your responses are identical. If my results are different at all I would need to notify people downstream.
- deathanatos 11y ago
  I've found it's a mix between the two extremes. Obviously, I can't start suddenly returning XML instead of JSON, because "I feel like it and it's cool"; it breaks everyone horribly, so that needs to be version 2. But if you insist on upping the version effectively any time you do, you're essentially saying that any side-effect (not just output) visible can't be fixed, except by duplicating the API and creating a new version, fixing it there, and moving the callers over (if you can — this, I've found is the hardest part[1]). Often, these are things that I feel like the spec is supposed to hash out: what is it supposed to do. If it strays from the spec, that doesn't necessarily require a new version number, especially if it doesn't break things. However, it has been my experience in that even the most benign changes will break things; you've got to be able to evaluate and figure out who is not following spec, and sometimes, how bad is the effect of the change if the clients didn't like it. (Is it so bad that, even though it's to spec, I should roll back? Or should the client fix the buggy behavior they've been depending on, and we can carry on in the meantime?) [1]: Mobile clients are out there. Unlike a web page, there's no way to edit/update them — you can push a new version, but will the users upgrade? At some point, you have to cut them, I suppose, but after how long? 6 months? <2% share among the user base? the active user base? What's an active user? (and now higher ups are involved, and you're in meetings…) [also]: https://xkcd.com/1172/ https://xkcd.com/1172/
- jedberg 11y ago
  > If my results are different at all I would need to notify people downstream. Presumably your API says what types of data the caller should expect. As long as you don't change that, they should be able to deal with the response changing. But really it's more about the fact that if you have a single monolith, if you want to make a change, you have to coordinate with everyone at the company, whereas if you have microservices, you only have to coordinate with those who are affected by the change.
  - IanCal 11y ago
    > Presumably your API says what types of data the caller should expect. As long as you don't change that, they should be able to deal with the response changing. The point I wanted to get across was that although a client won't break, I'd still want to talk to those pulling data from the system. I was disagreeing with the statement "you can make as many changes to your service as you want without any coordination." > But really it's more about the fact that if you have a single monolith, if you want to make a change, you have to coordinate with everyone at the company, whereas if you have microservices, you only have to coordinate with those who are affected by the change. Yes, it does lower the hurdles to getting something out.