On Thu, Mar 21, 2019 at 11:55 PM Nuwan Dias wrote:
>
>
> On Fri, Mar 22, 2019 at 2:17 AM Nuwan Bandara wrote:
>
>> Hi All,
>>
>> I stumbled upon one of Roy Fielding tweets -
>> https://twitter.com/fielding/status/376835835670167552 :)
>>
>
> I unfortunately don't agree with this tweet :). I don't understand how
> having a v1 makes your API non-evolvable. IMO the sole purpose of having v1
> is to say the API will/should evolve to v2, v3, likewise.
>
I think the idea there is the semantics of the API intermingles with the
identifier of the API. in the Web URI is treated as the identifier of the
resource and by definition the identifier should not change but the
underline implementation can change.
I read an interesting idiom for this: it's like putting someones age after
their name whenever you call them. Like you call John20 today and next year
you call him John21 ;) also the web treats identifiers in a special way.
Caches, crawlers, forms and bookmarks all use URI identifiers, but if those
change regularly, it doesn't make sense.
Anyways this is one of those religious debates, we can agree to disagree.
However, being a API Management vendor we should enable all possible
options for API developers to version their APIs. At the first glance our
platform seems to be opinionated towards URI based versioning, other
options can be archived but not through first class features. (Versioning
through mime headers, query param versioning, no versioning and backend
revision tracking etc.)
@Chintana also found this in youtube -
https://www.youtube.com/watch?v=kVM-5vQymIA
Regards,
Nuwan
>
>> and started digging bit on api versioning. Right now we encourage API-M
>> users to make API versions explicit in the API URI. which means a sample
>> URI is /{context}/{version}/{resource}
>>
>> example: /pizzahut/v1/order
>>
>> however this is not the best option. We are gateway providers, IMO we
>> should give options.
>>
>
> We give an option to omit the version from the URI by marking the API as
> the default version to route to. So you can access this API through
> /pizzahut/order (no need v1). The gateway will route the request to
> whatever version is selected as primary (default).
>
>>
>> some good alternatives are allow API developers to use headers to
>> communicate version info like
>>
>> GET /pizzahut/order
>> Accept: application/vnd.pizza.order.v1+json
>>
>> or something similar.
>>
>> I know we can handle custom headers in mediation, but we should provide
>> this by default, maybe provide that as the default option rather than URL
>> based explicit option.
>>
>> Some good reading -
>> https://www.mnot.net/blog/2012/12/04/api-evolution.html
>>
>> Regards,
>> /Nuwan
>>
>> --
>>
>>
>> *Thanks & Regards,*
>> *Nuwan Bandara | Director - **Solutions Architecture, WSO2 Inc.*
>> *+1 646 643 8618 | +1 650 745 2169 Ext 4212 | http://nuwanbando.com
>> *
>>
>>
>
>
> --
> *Nuwan Dias* | Director | WSO2 Inc.
> (m) +94 777 775 729 | (e) nuw...@wso2.com
> [image: Signature.jpg]
>
--
*Thanks & Regards,*
*Nuwan Bandara | Director - **Solutions Architecture, WSO2 Inc.*
*+1 646 643 8618 | +1 650 745 2169 Ext 4212 | http://nuwanbando.com
*
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
