<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Suhas Chatekar on Medium]]></title>
        <description><![CDATA[Stories by Suhas Chatekar on Medium]]></description>
        <link>https://medium.com/@suhas_chatekar?source=rss-fd0546bc3c39------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*2e2lEgAnXvxZVWFS5lHSHw.jpeg</url>
            <title>Stories by Suhas Chatekar on Medium</title>
            <link>https://medium.com/@suhas_chatekar?source=rss-fd0546bc3c39------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 12:07:26 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@suhas_chatekar/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Blockchain and disruption of trust models]]></title>
            <link>https://medium.com/@suhas_chatekar/blockchain-and-disruption-of-trust-models-116c8a4b8975?source=rss-fd0546bc3c39------2</link>
            <guid isPermaLink="false">https://medium.com/p/116c8a4b8975</guid>
            <category><![CDATA[blockchain]]></category>
            <dc:creator><![CDATA[Suhas Chatekar]]></dc:creator>
            <pubDate>Tue, 19 Mar 2019 12:25:25 GMT</pubDate>
            <atom:updated>2019-03-19T12:25:25.371Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/960/1*XoCkyhmAbYF1HoPefdFIPQ.png" /></figure><p>You will rarely hear a blockchain argument that does not talk about trust. People use it in different contexts which confuses others who are still trying to understand what blockchain is. I have also been asked to exactly define what I mean by trust. I will try to explain that in this article through the trust models that we live in.</p><h3>Two trust models</h3><p>One of the ways I describe blockchain is that it has the potential to disrupt the trust models that we live in. We live in two different trust systems. The first one is where we inherently trust everything. A prime example of this is the government issued currency. We inherently trust the money that is in our wallets. We trust that its value within the local market will more or less stay the same and it would remain a usable currency for our lifetime.</p><p>The second trust model that we live in is the one where we inherently distrust everything. Almost everything we do with our money fits into this trust model. Over the years we have set up laws, regulations and legal systems that protect us from unexpected outcomes when we transact using the money. The very reason the laws, regulations and the legal system exists is that we do not inherently trust the party that we are transacting with. o</p><h3>Two waves of blockchain revolution</h3><p>I like to divide the blockchain revolution into two waves. The first wave, started by bitcoin and resulted in the creation of hundreds of other cryptocurrencies aims to disrupt the first trust system. It promises to remove the need for the government, central and commercial banks that we tend to inherently trust when it comes to money. And it does that by offering an alternative currency that works without a need for the guarantee from a government.</p><p>The second wave of blockchain revolution started with the creation of Ethereum. Ethereum, for the first time, made it possible to write smart contracts on the blockchain. While Ethereum’s cryptocurrency, Ether, promises to disrupt the first trust system like bitcoin, Ethereum (and another blockchain with support for smart contracts) itself promises to disrupt the second trust system that we live in. Smart contracts are computer programmes that run on the blockchain. Once a smart contract is added to blockchain it cannot be changed by anyone. anyone. Parties having access to the smart contract can view it but they cannot change it. Two parties transacting with each other can agree to a process that going to complete the transaction between them. This agreed process can then be encoded into a smart contract and added to the blockchain. This mechanism provides a guarantee that the transaction gets executed as agreed and no other party with malicious intent can amend it. As the founder of Ethereum once said — code becomes the law. The trust shifts from the legal system to the blockchain.</p><p>This sounds very exciting, but remember that it is too early to predict what direction the technology will take. Blockchain seems to have a promising future but only time will tell how much of it will come to fruition.</p><p><em>Originally published at </em><a href="http://chatekar.com/Blockchain-and-disruption-of-trust-models/"><em>chatekar.com</em></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=116c8a4b8975" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Convert a JavaScript project to Typescript, one file at a time]]></title>
            <link>https://medium.com/@suhas_chatekar/convert-a-javascript-project-to-typescript-one-file-at-a-time-26f523051ee7?source=rss-fd0546bc3c39------2</link>
            <guid isPermaLink="false">https://medium.com/p/26f523051ee7</guid>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Suhas Chatekar]]></dc:creator>
            <pubDate>Tue, 22 Aug 2017 10:26:13 GMT</pubDate>
            <atom:updated>2017-08-22T10:26:13.543Z</atom:updated>
            <content:encoded><![CDATA[<p>JavaScript is good but, like me, if you come from statically typed languages then it becomes a bit annoying to deal with lack of types when the project grows big. Luckily there is Typescript but adding Typescript retrospectively may not be a very straight-forward job. Recently I successfully converted a sizeable JavaScript project into Typescript, <strong>one file at a time</strong>. Converting one file at a time to Typescript is really powerful because then you can make the change incrementally without having to stop delivering the features that your product owner wants. I tried doing this different ways. Here, I will talk you through the one that worked.</p><p>This a long-ish read. I have divided the content into three main sections</p><ol><li>Adding typescript config and webpack</li><li>Adding Type declaration files</li><li>Convert the code into typescript</li></ol><p>The source code for this article is on <a href="https://github.com/schatekar/js-to-ts">GitHub</a>. It is a very simple calculator application with just two files. I think that is enough files to demonstrate the approach. The initial javascript source is in <a href="https://github.com/schatekar/js-to-ts">master branch</a>. the changed source code at the end of every section is in appropriate branches in the same repository.</p><p>Let’s drive straight in then.</p><h3>1. Adding typescript config and webpack</h3><p>Any typescript code has to be transpiled down to JavaScript before it can be run. That is where webpack comes in handy. If you have never used Webpack before, then I recommend reading <a href="https://www.smashingmagazine.com/2017/02/a-detailed-introduction-to-webpack/">A detailed introduction to webpack</a> before proceeding.</p><p>We start by installing webpack using the following command</p><pre>npm install --save-dev webpack</pre><p>Note that we are adding webpack as a development dependency. This is because it’s only used to convert typescript code into javascript. Next we need a webpack configuration. Add a new file named webpack.config.js at the root of the project and the following content to it</p><pre>var path = require(&#39;path&#39;); <br>var webpack = require(&#39;webpack&#39;); </pre><pre>module.exports = { <br>    entry: { index: &quot;./index.ts&quot; }, <br>    target: &#39;node&#39;, <br>    module: { <br>        loaders: [ { <br>            test: /\.ts(x?)$/, loader: &#39;ts-loader&#39; <br>         }, <br>         { <br>            test: /\.json$/, loader: &#39;json-loader&#39; <br>         } ] <br>    }, <br>    plugins: [ <br>         new webpack.DefinePlugin({&#39;process.env.NODE_ENV&#39;: &#39;&quot;production&quot;&#39;}) ], <br>     resolve: { <br>         extensions: [&#39;.ts&#39;, &#39;.js&#39;, &#39;.json&#39;] <br>     }, <br>     output: { <br>         libraryTarget: &#39;commonjs&#39;, <br>         path: path.join(__dirname, &#39;lib&#39;), <br>         filename: &#39;[name].js&#39; }, <br>};</pre><p>Let’s quickly go over the contents of this file. We have imported path module to make it easy to do some path manipulation in the output section of the config. We have also imported webpack to define a plugin in the plugins section. Let&#39;s not worry about this just yet.</p><p>The file is basically just exporting a JSON object which webpack uses as configuration. Webpack has a large number of configuration options but the ones we have configured here are minimal ones needed for a typescript project. Let’s look into each of the configuration we have defined in this object</p><h3>entry</h3><p>This tells webpack where to begin transpiling. Webpack will start with the files specified in entry, converts them into JS (see module section next) and then goes through every module that these modules import till it has reached the end of the tree. We do not have to have a single entry point. We can provide any number of entry points we want here. We have specified index.ts as our entry point. This file does not exist yet. We will eventually convert our entry module index.js into index.ts.</p><h3>target</h3><p>Target tells webpack where you want to run the final Javascript code. This is important because the code that gets generated to be run on server side is different from the code that gets generated to be run in a browser. For this example we specify node which is for the code that gets run on the server side</p><h3>module</h3><p>This is where the most of the magic happens. We have specified on the loaders part of this object. Webpack uses different loaders to transpile files. In our case, we have a ts-loader to transpile any Typescript files and a json-loader which I have left there in case we add a json file later on. Loaders need to be installed separately and they come as their own NPM packages. For our config, we need to install ts-loader and json-loader usin the following command.</p><pre>npm install --save-dev ts-loader json-loader</pre><h3>plugins</h3><p>Let’s ignore that for a moment</p><h3>resolve</h3><p>This is where you tell webpack which file extensions to scan during its transpilation process. We have added .ts and .js both as we want to convert one js file to ts at a time. This means, we will have a mix of js and ts files in our project and we want webpack to consider both</p><h3>output</h3><p>This is where we tell webpack how do we want the output of the transpilation to appear. We are saying that we want the output files to be named after the key name we used for the file in the entry section. We want the output files to be copied into a folder named lib under the current directory. And we want webpack to use commonjs module system.</p><p>Again, if this is the first time you are using webpack, then do not worry too much about the content of this file. This is a minimal config that just works for any server side code.</p><p>Next we need a Typescript config. Add a file named tsconfig.json to the project. Again, the minimal contents for this file are as below</p><pre>{<br>    &quot;compilerOptions&quot;: {<br>        &quot;target&quot;: &quot;es5&quot;,<br>        &quot;module&quot;: &quot;commonjs&quot;,<br>        &quot;noImplicitAny&quot;: true,<br>        &quot;lib&quot;: [<br>        &quot;es5&quot;,&quot;es2015&quot;, &quot;es6&quot;, &quot;dom&quot;<br>        ]<br>    }<br>}</pre><p>This is telling the Typescript compiler that we want the resulting JS to be ES5 compliant and we want to use commonjs as our module system. We have also added a noImplicitAny which is set to true. This forces you to declare any variable of type any instead of leaving the type declaration out and compiler marking the variable as any. This helps to catch cases where we forget to declare type for a variable.</p><p>Next we need a way to invoke webpack. There are two ways you can do this. The webpack npm package that we installed earlier, you can install that globally and just run webpack from the console at the root directory of the project. Or you can add an NPM script in your package.json that uses the locally installed webpack version like below</p><pre>&quot;scripts&quot;: {<br>    &quot;build&quot;: &quot;node_modules/.bin/webpack --config webpack.config.js&quot;<br>},</pre><p>Note that I have padded a --config flag which is not really needed because webpack looks for a file named webpack.config.js by default. But if you prefer to name your webpack config file differently then make sure you pass the --config flag.</p><p>The source code at the end of this section is in <a href="https://github.com/schatekar/js-to-ts/tree/add-webpack">add-webpack</a> branch.</p><h3>2. Add Type declaration files</h3><p>We need to find the first module that we can safely convert to Typescript. This is usually the entry module of our project. In our example, that would be index.js. To use the full power of Typescript in our converted module, we need to have type declaration files for other modules that this module is dependent on. There are two concepts around type declaration files that we need to understand. I am assuming that you know what type declaration files are, if not, I would recommend reading the <a href="https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html">official guidance on this topic</a></p><ol><li>We need to explicitly install type declaration files for any external module. In our example, we have an external module called prompt-sync for which we will need to install type declaration files</li><li>For our own modules that we have not converted into Typescript yet, we need to write type declaration files ourselves as a stop-gap arrangement till the time we convert that module into Typescript</li></ol><h3>Installing type declaration files for external modules</h3><p>Type declaration files for most NPM packages are already made available by the community. We can run the following command to install the Type declaration files for our prompt-sync package</p><pre>npm install --save-dev @types/prompt-sync</pre><p>If the type declaration file is available, it will get installed. If not, you will see an error. You will need to create the necessary type declaration files yourselves.</p><h3>Creating type declaration files for own modules</h3><p>Type declaration files for a module contain interface, function and type declarations for the bits that the module exports. They are declared in a file with extensiond.ts and named after the module name or index.d.ts. For instance, the type declaration file for the prompt-sync module that we just installed is named index.d.ts and you can find it in node_modules/@types/prompt-sync folder. That is one of the known location that typescript compiler searches during module resolution. You can read more about the module resolution process that typescript compiler follows in the <a href="https://www.typescriptlang.org/docs/handbook/module-resolution.html">Typescript Handbook</a>. One of the strategies used by the compiler to resolve modules is to look for a type declaration file matching the module name at the same location as the imported module. For instance, if we import a module like below</p><pre>import * as calc from &#39;./calculator&#39;</pre><p>then typescript compiler will look for a calculator.ts or calculator.d.ts file in the current directory. We can use this mechanism to put our existing calculator.js file behind a type declaration by creating a file calculator.d.ts like below</p><pre>declare module calculator {<br>    export function add(a :number, b :number): number<br>    export function subtract(a :number, b :number): number<br>    export function multiply(a :number, b :number): number<br>    export function divide(a :number, b :number): number<br>}<br>export = calculator;</pre><p>Notice that this is exposing the same methods as our calculator module but has annotated arguments and return values with a number type. This file needs to be placed next to calculator.js.</p><h3>Creating Type declaration files for external modules</h3><p>We do not have any external module in this example that does not have Type declaration files available. But if that were the case with you, you can combine the knowledge from the above two points. First you build your own type declaration file and name it index.d.ts. This can include only the methods/interfaces from the external module that you are using in your code. This type declaration file file needs to be kept under the folder node_modules/@types/{module_name}/</p><p>I have never personally tried this so cannot vouch for reliability but this is what community defined Type declaration files are doing under the hood. The source code at the end of this section is in <a href="https://github.com/schatekar/js-to-ts/tree/add-types">add-types</a> branch.</p><h3>3. Convert the entry module into TypeScript</h3><p>Finally we are ready to convert our first module into TypeScript. There is not much really in this step. Rename index.js to index.ts and start rewriting the module in typescript. If you use the import syntax for bringing in the dependent modules then TypeScript compiler will look at the type declaration files of the target module and enforce type checking in addition to usual Javascript compiler checks. Here is how my converted index.ts file looks like</p><pre>import * as p from &quot;prompt-sync&quot;<br>import * as calc from &quot;./calculator&quot;<br>let prompt = p();<br><br>function readInput() {<br>  console.log(&quot;Welcome to the calculator. Choose one of the following options&quot;);<br>  console.log(&quot;1. add&quot;);<br>  console.log(&quot;2. subtract&quot;);<br>  console.log(&quot;3. multiply&quot;);<br>  console.log(&quot;4. divide&quot;);<br>  console.log(&quot;5. exit&quot;);<br><br>  var option = prompt(&quot;&gt;&gt; &quot;);<br><br>  if (option !== &quot;5&quot;) {<br>    console.log(&quot;Enter the first number&quot;);<br>    let a = parseInt(prompt(&quot;&gt;&gt; &quot;));<br><br>    console.log(&quot;Enter the second number&quot;);<br>    let b = parseInt(prompt(&quot;&gt;&gt; &quot;));<br><br>    let c;<br>    switch(option){<br>      case &quot;1&quot;: {<br>        c = calc.add(a, b);<br>        console.log(`a + b = ${c}`);<br>      }<br>      break;<br><br>      case &quot;2&quot;: {<br>        c = calc.subtract(a, b);<br>        console.log(`a - b = ${c}`);<br>      }<br>      break;<br><br>      case &quot;3&quot;: {<br>        c = calc.multiply(a, b);<br>        console.log(`a * b = ${c}`);<br>      }<br>      break;<br><br>      case &quot;4&quot;: {<br>        c = calc.divide(a, b);<br>        console.log(`a / b = ${c}`);<br>      }<br>      break;<br>    }    <br><br>    readInput();<br>  }<br>}<br><br>readInput();<br><br>console.log(&quot;Thank you for using calculator. Good Bye&quot;);</pre><p>Yeyy. We converted our first module from javascript to typescript. If you run npn run build at this point, you will notice the webpack successfully gives us a packaged bundle in lib/index.js that is ready to use.</p><p>The source code at the end of this section is in <a href="https://github.com/schatekar/js-to-ts/tree/convert-entry-module">convert-entry-module</a> branch.</p><h3>4. Keep going</h3><p>Converting the first javascript file is a big win. You have basic plumbing in place now to take on the bigger task. You may want to expand your webpack configuration to include other types of files you may have in your project, add production build steps like minification, uglification etc. At the same time, you also need to keep converting more and more files from javascript to typescript. The next logical step is to get rid of our own type declaration files by converting the javascript modules into typescript. Let’s change the calculator module to get rid of calculator.d.ts. There are a number of ways, you can rewrite calculator module using typescript. The simplest is to just export the four methods in the module like below.</p><pre>export function add(a: number, b: number): number {<br>  return a + b;<br>}<br><br>export function subtract(a: number, b: number): number {<br>  return a - b;<br>}<br><br>export function multiply(a: number, b: number): number {<br>  return a * b;<br>}<br>export function divide(a: number, b: number): number {<br>  return a / b;<br>}</pre><p>Delete the calculator.d.ts file and re-run npm run build you would get your packaged bundle in lib/index.js.</p><p>That’s it. We have converted everything in this project from javascript to typescript. The source code at the end of this section is in <a href="https://github.com/schatekar/js-to-ts/tree/keep-going">keep-going</a> branch.</p><p><em>☞ If you like my article, please </em><strong><em>don’t forget to click ❤ to recommend </em></strong><em>it to others.</em></p><p><em>Also, to be notified about my new articles and stories, follow me on </em><a href="https://medium.com/@suhas_chatekar"><em>Medium</em></a><em> and </em><a href="https://twitter.com/suhas_chatekar"><em>Twitter</em></a><em>. You can find me on </em><a href="https://www.linkedin.com/in/chatekar"><em>LinkedIn</em></a><em> as well. Cheers!</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=26f523051ee7" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Return well-formed error responses from your REST APIs]]></title>
            <link>https://medium.com/@suhas_chatekar/return-well-formed-error-responses-from-your-rest-apis-956b5275948?source=rss-fd0546bc3c39------2</link>
            <guid isPermaLink="false">https://medium.com/p/956b5275948</guid>
            <category><![CDATA[rest]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[rest-api]]></category>
            <category><![CDATA[software-architecture]]></category>
            <dc:creator><![CDATA[Suhas Chatekar]]></dc:creator>
            <pubDate>Fri, 18 Aug 2017 13:43:47 GMT</pubDate>
            <atom:updated>2017-08-18T14:01:27.484Z</atom:updated>
            <content:encoded><![CDATA[<p>REST recommends using standard HTTP status codes to indicate what has happened on the server in response to a request. Errors from 4xx and 5xx family are used to indicate that request is not processed and there is some error either on the client side or on the server side e.g. 401 Unauthorised is used to indicate that the request cannot be processed because it does not anything to prove the identity of the sender. Standard HTTP status codes are a good starting point to indicate error condition but they are not enough. Especially if you are developing APIs that are consumed by large number of developers or are open to access by anyone then you may want to return well formed error responses that provide more details around the error. Initial inspiration for this idea comes from <a href="https://geemus.gitbooks.io/http-api-design/content/en/responses/generate-structured-errors.html">Generate Structured Errors</a> chapter of the GitBook <a href="https://geemus.gitbooks.io/http-api-design/content/en/index.html">HTTP API Design Guide</a>. I personally recommend this book to anyone who wants practical advice on building REST APIs.</p><p>At <a href="http://collinsongroup.com/">Collinson Group</a> we have started returning JSON similar to the one below in some 4xx/5xx responses</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/1711192fa06abbd85afc32211b2b836c/href">https://medium.com/media/1711192fa06abbd85afc32211b2b836c/href</a></iframe><p>The above JSON is returned in response body whenever we believe that the standard HTTP status is not enough for the calling application to know what has gone wrong. Let’s quickly see what purpose each of these fields fulfil and what values they may contain.</p><h4>errorCode</h4><p>As the name suggests this field holds an unique error code. We decided to use string based error codes as they are easy to read. People also use numbers for this. I personally feel that numbers are cryptic for this kind of information.</p><h4>field</h4><p>Name of the field which has this error. This is the same name that appeared in the incoming request.</p><h4>originalValue</h4><p>This field contains the original value from the request. This is optional in most cases. While client can make use of this information if they need to, there is one situation where we found returning this information to be useful. We had a POST API that accepted an array of the same resources. If more than one resource fail the same validation on the same field then we end up returning same error response twice. How will client know which resource was in error. Adding original value in the response helps track the client which resource in the request had error.</p><h4>message</h4><p>This field contains an end user friendly message. If the consumer of the API is a front end application then it may choose to use this message directly to convey details of the error to the end user. There are two things to note around this field. One, the example above shows the message as tokenised with {email} as a token in the message. The API should replace this token with the original value from the request before returning the response. Two, this message should be localised in a language that client prefers. This assumes that you have got a mechanism in your API for your clients to specify a preferred language.</p><h4>helpUrl</h4><p>This field contains URL to a page that describes this particular error in more detail. The help page may answer the following questions (in addition to any other details you may want to include)</p><ol><li>What causes this error? Examples will help here.</li><li>How to fix this error?</li><li>If you continue to get the error, how do you get help?</li></ol><p>I call this mechanism <strong>discover-able documentation</strong> because developers of the client applications do not have to know where to find this documentation, when they encounter an error, they automatically discover appropriate documentation instantly.</p><h3>Error codes that we use</h3><p>The following list of error codes satisfies most common field level errors.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aZd_ZxOMHp2K3Xw4gUAhmQ.png" /></figure><p>There are some domain specific error codes we use that I have omitted. You can define as granular error codes as possible. Are you using well formed error responses in your APIs? Do you find this approach useful?</p><p><em>☞ If you like my article, please </em><strong><em>don’t forget to click ❤ to recommend </em></strong><em>it to others.</em></p><p><em>Also, to be notified about my new articles and stories, follow me on </em><a href="https://medium.com/@suhas_chatekar"><em>Medium</em></a><em> and </em><a href="https://twitter.com/suhas_chatekar"><em>Twitter</em></a><em>. You can find me on </em><a href="https://www.linkedin.com/in/chatekar"><em>LinkedIn</em></a><em> as well. Cheers!</em></p><p><em>Originally published at </em><a href="http://blog.chatekar.com/return-well-formed-error-responses-from-your-rest-apis/"><em>blog.chatekar.com</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=956b5275948" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why every customer care team should start using ChatBots?]]></title>
            <link>https://medium.com/@suhas_chatekar/why-every-customer-care-team-should-start-using-chatbots-59948953d7d4?source=rss-fd0546bc3c39------2</link>
            <guid isPermaLink="false">https://medium.com/p/59948953d7d4</guid>
            <category><![CDATA[slackbot]]></category>
            <category><![CDATA[messenger-bots]]></category>
            <category><![CDATA[chatbots]]></category>
            <category><![CDATA[conversational-ui]]></category>
            <dc:creator><![CDATA[Suhas Chatekar]]></dc:creator>
            <pubDate>Thu, 08 Jun 2017 10:10:37 GMT</pubDate>
            <atom:updated>2017-06-08T10:10:37.966Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/450/0*OMYC47gyJmcAvHHd.png" /></figure><p>It’s only been a little over 12 months, since the concept of chatbots has gone truly mainstream. Announced at Facebook’s 2016 Developer Conference F8, chatbots have come a long way. Whilst relatively new in the Western world, chatbots made their first appearances in 2013 — on China’s leading social media and messaging platform WeChat.</p><p>For context, chatbots are defined as follows</p><blockquote><strong>A chatbot is a computer program which maintains a conversation with a user in natural language, understands the intent of the user, and sends a response based on business rules and data of the organisation. A user interacts with a chatbot via a mobile messenger (such as Facebook Messenger, Skype, WhatsApp or Slack), SMS, or website. Artificial Intelligence (AI) is typically embedded in a chatbot to help it better understand the context of the conversation.</strong></blockquote><p>A widely adopted use case for chatbots to date has been seen in the field of service provisioning within verticals of (highly) predictable enquiries / requests (think flight / hotel booking requests or indeed FAQ type enquiries).</p><p>Purpose of this article is to provide the art of the possible (and a bit beyond) of chat bots today and how they have found their way into many daily tasks across industries.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/341/0*i93kApS9cIi8dni9." /></figure><p>Regional cut of most used social media &amp; messenger platforms — note the complete difference for China.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/624/0*IoiU54fvVq6S2sPF." /></figure><h3>INSIGHT NO. 1: Consumers are busy and want their complaints, enquiries and questions addressed quicker, more easily and in a form that can easily be fitted into day to day activities. Messenger based conversational interfaces are quickly becoming the channel of choice for consumers to engage with brands.</h3><blockquote><em>89% of global consumers rate their overall perception of bots as “positive” or “neutral”</em></blockquote><p>Today, the most common way for a customer to get their questions and concerns resolved, is to call the customer care centre.<br>Making a call is both, time consuming and also more often than not far from the most convenient form of communication and interaction. In parallel, consumer behaviour has shifted significantly towards messaging for person to person communication rather than calling someone directly. Besides that, most customer care centres have waiting times, often providing details via (tedious) IVR systems. Even when there is close to zero holding time, getting to the right customer care agent involves listening to a handful of instructions and dialing a few additional numbers. In short: far from frictionless, easy and delightful. Especially when consumer is already worried, frustrated or plain angry about having to get in touch with a contact centre.</p><p>The rise of messenger platforms and with them the increasing popularity of chatbots, has opened an additional communications and engagement channel between brands and consumers, which is growing in popularity — across all consumer segments. Chatbots come with the huge advantage of instant availability and a high degree of contextualisation — making it a significantly stronger channel for customer care.</p><h3>INSIGHT NO. 2:Bots can get to the bottom of customer’s queries faster than agents can</h3><p>Key driver for the difference in speed of resolution is predominantly down to</p><ul><li>call centre infrastructure (i.e. how information is stored in knowledge hub systems and tools available to the agents)</li><li>the guided UI — question &amp; answer journey — chatbots are lending themselves to</li></ul><p>Against the backdrop of increasingly time-poor consumers and constantly growing expectations to one-touch resolution in the the context of customer care, this is a big bonus. Admittedly, this super streamlined ‘remedy journey’ will largely be dependant on the maturity of the bots in question, but a lot of steps we put in the way of an agent today are just not needed for bots. For example, the moment a customer starts chatting with a bot, the bot will know everything about the customer without having to ask a single question. If the customer needs to be bounced to a different bot agent, it can happen instantly without any explicit input from the customer.</p><h3>INSIGHT NO. 3: Bots can get back to customer without needing any reminders or phone calls</h3><p>A lot of customer complaints today require the contact centre agents to call back the customers when there is an update available. This is a tedious job as the human agents would need to keep a track of a number of things like status of the complaint, the best number to reach the customer on, best time to call the customer. If the call goes unanswered, another attempt is needed. On one hand, this offers a personalised customer experience. On the other hand, missed calls or calls at a wrong time would end with a more annoyed customer.</p><p>With a completely automated back end system in place, bots can be told programmatically when a status update is available on the customer complaint, and bots can send a message to the customer on the same thread on which the customer raised the complaint in the first place.</p><h3>INSIGHT NO. 4: Sharing knowledge among bots is a zero time and zero cost affair</h3><p>The call centre industry has always tried to optimise itself. They do it by going through the past records of customer complaints, how the complaints were addressed and use that knowledge to build training for the staff. This is a slow, time consuming and expensive process. And often out of date by the time the agents have received the relevant training. Wouldn’t it be great if learning from one human agent from a previous customer’s complaint can be instantly transferred to all the other human agents?</p><p>Here come the bots: each bot powered session is a (slightly) different form of executing instances of the same bot code. What one instance learns from their previous handling of a case can be instantly transferred to all other instances of the bot agents. This can happen at no extra cost and without any human intervention.</p><h3>INSIGHT NO.5: Bots can help transform contact centre agents into “customer happiness agents”</h3><p>When all regular customer complaints are handled by bots entirely, the human agents have significant more flexible time and mind space to deal with more complex complaints. Traditionally, less frequently occurring complaints is where the lion share of friction and bad customer experience is rooted. It is just as frustrating for agents, who are trained to run through a playbook, often within a tightly defined request handling time metric, as it is for customers, to forcefully resolve an issue — mainly because time’s up! With handling of repetitive questions and complaints being taken care of by bots, agents can be up-skilled to deal with such “out-of-the-playbook” complaints more effectively.</p><h3>Closing remarks</h3><p>The bot industry is still in its infancy — that said, it’s come a long way since first introduced at mass scale by Facebook in 2016. Also, a few instances of the above outlined services are not (yet) entirely possible with the technology we have today.</p><p>What is clear however are the following indicators:</p><ul><li>Overall, chat bots have seen a significant rise since FB first introduced them in 2016</li><li>The sheer volume of brands / B2B service providers who have joined the conversational commerce and customer care channel (=conversational UI) is indicative itself that this is more than just a trend</li><li>Messenger platforms + automation = bots <br>A winning formula in today’s time poor consumer and streamlining and cost reducing business world</li></ul><p>But at the same time, the research in this space is happening at an unprecedented rate. A record number of funded startups are working towards building technology that is going to leap the world forward earlier than we imagine. The key for any business to take advantage of all this is not to leave themselves out: test, learn and iterate!</p><p><em>☞ If you like my article, please </em><strong><em>don’t forget to click ❤ to recommend </em></strong><em>it to others.</em></p><p><em>Also, to be notified about my new articles and stories, follow me on </em><a href="https://medium.com/@suhas_chatekar"><em>Medium</em></a><em> and </em><a href="https://twitter.com/suhas_chatekar"><em>Twitter</em></a><em>. You can find me on </em><a href="https://www.linkedin.com/in/chatekar"><em>LinkedIn</em></a><em> as well. Cheers!</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=59948953d7d4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Dear product owners, do not hold your team to their estimates]]></title>
            <link>https://medium.com/@suhas_chatekar/dear-product-owners-do-not-hold-developers-to-their-estimates-c9a87c70641e?source=rss-fd0546bc3c39------2</link>
            <guid isPermaLink="false">https://medium.com/p/c9a87c70641e</guid>
            <category><![CDATA[product-management]]></category>
            <category><![CDATA[agile]]></category>
            <category><![CDATA[software-estimation]]></category>
            <dc:creator><![CDATA[Suhas Chatekar]]></dc:creator>
            <pubDate>Fri, 02 Jun 2017 08:44:10 GMT</pubDate>
            <atom:updated>2017-06-02T09:32:25.354Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/900/0*TzlM5rBpW25K855q.jpg" /><figcaption>Estimates are never correct</figcaption></figure><p>To all the product owner friends out there — if you keep holding your team to their estimates, one of the two will happen. Either they will find ways to work around your behaviour or you will end up with a product that is sub-optimal in quality.</p><p>Estimates by definition are guesses. And they can be as correct or as wrong as any other guess. Closeness of an estimate to reality depends on a number of things</p><ol><li>Has the team worked on something like that before?</li><li>How skilled the team is at using the tools and tech?</li><li>How experienced is the team to understand the complexity of business requirement?</li><li>Does the new work result in re-doing some of the previously done work?</li><li>How good is the team at working out #4?</li><li>How quickly can the team find out they are on the wrong path and how quickly can he recover?</li><li>Do the processes slow the team down?</li><li>If #7 is the case, does the team know the extent?</li></ol><p>I am sure I have not covered everything here. But you get the gist — it’s impossible to come up with an estimate that is close to reality, specifically when the reality itself is not constant which is usually the case.</p><p>If you, as a product owner, fail to realise this and keep holding team for their estimates, then they will learn to work around your behaviour by inflating the estimates or by cutting corners. Both are harmful to your product. So how do you deal with such situation. Even you have a budget that you do not want to blow through the roof.</p><h3><strong>Keep an eye on team’s velocity</strong></h3><p>In an ideal scenario, the velocity of a team should increase over time, everything being constant. This is because team keeps getting better at understanding the domain and using the tools and the tech. If the velocity is going down or is constant then it’s time to ask the right question.</p><h3><strong>See if you are adding more complex features to the backlog or changing scope</strong></h3><p>Before you set out to ask the right questions, take a good look at your backlog to find out</p><ol><li>If the recent features that the team delivered were more complex than the ones they delivered earlier</li><li>If the scope of features has changed after the initial estimate was provided</li></ol><p>If the answers to above are positive then it’s worth knowing how the team felt about the change in complexity or scope. If nothing else, it will help build relationships</p><h3><strong>Find out what caused velocity to go down</strong></h3><p>A lot of reasons can contribute to a low velocity. Have a chat with your team and understand the challenges they faced. Did they misunderstood a requirement? Did they developed something that was not in the scope? Help them understand the priority of the features by attaching business value to each feature. Sometimes it could be a simple and silly mistake but who does not make mistakes? The key is learning from the mistakes.</p><h3><strong>Respect the practices that team follows</strong></h3><p>Some of the practices like TDD and DevOps result in significant cost investment at the beginning of the project and generally a higher ongoing cost of delivery. But remember, these practices help tremendously in our ability to deliver a quality software and turning around new features quickly. Our industry has learned in recent years what it means to go from development environment to production within hours than days or weeks. It is the practices like TDD and DevOps that make such speed of delivery possible. It comes at a cost, however, the key is remember that even the efforts required for TDD and DevOps needs to be estimated. Like any other estimate, these estimates are likely to go wrong as well.</p><h3>Understand that developers love upkeep of their code</h3><p>Developers are continuously enhancing their coding skills. This means, every now and then, they would look at their old code and realise how it can be made better. Upkeep of code quality needs time investment and in some cases may bring the velocity down. In the absence of an understanding between product owner and the team, developers would either ignore such enhancements and go on building tech debt that will eventually crumble the product down. Or they would just go ahead and invest time bringing down the velocity.</p><p>Engage with your team, understand why it is important to maintain code quality. Try to strike a balance between an acceptable code quality and velocity.</p><h3><strong>And lastly remember this iron triangle of software quality</strong></h3><p>If you want your software at a low cost and delivered fast, then you are most likely to lose out on quality.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/934/1*UhAS1_5OEjEACUVd4zZWOA.png" /><figcaption>Iron triangle of software quality</figcaption></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c9a87c70641e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to balance chunkiness against chattiness when designing your REST API]]></title>
            <link>https://medium.com/free-code-camp/three-ways-to-balance-between-chunkiness-and-chattiness-of-your-rest-api-67e60b7bcca7?source=rss-fd0546bc3c39------2</link>
            <guid isPermaLink="false">https://medium.com/p/67e60b7bcca7</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[startup]]></category>
            <category><![CDATA[tech]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[graphql]]></category>
            <dc:creator><![CDATA[Suhas Chatekar]]></dc:creator>
            <pubDate>Mon, 27 Feb 2017 21:39:58 GMT</pubDate>
            <atom:updated>2017-03-02T00:16:45.146Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LPqttE_5_wbbElPa8J6nxQ.jpeg" /></figure><p>One of the challenges of building any API is that you don’t know who will use your API, or how they will use it.</p><p>You may have an internal consumer who calls your API over a LAN connection. This consumer would not mind making massive API responses (chunky), or making several API calls to get all the different chunks of data that they want (chatty).</p><p>Or you may have an external consumer connecting over the internet. This consumer would like to make a small number of network calls. Such consumers also want the API to return just enough data.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/752/1*UXNH96dwNg_hj-txjStXVQ.png" /></figure><p>Consumers connecting from a mobile network are particular about network calls. For them, network calls result in carrier charges for their users. Large amount data returned by APIs is not ideal for them as it may lead to a lot of battery usage while processing it.</p><p>As an API developer, you do not get to decide whether your API should be chatty or chunky or none. Consumers of your API want to decide that. Truth is, most APIs have consumers from both the camps. So how do you deal with these demands? The easy answer is by giving more power to the consumers of your APIs. Let the consumers be in the driving seat and let them tell your API what do they want.</p><p>In this article, I am going to talk about three techniques that let you do that.</p><h3>Technique #1: Use Lazy Get to control the size of your payload</h3><p>Most Object Relational Mapper(ORM) tools have a feature called Lazy Loading. ORMs use this feature to return only the top level entity when they execute a SQL script. Any associated entities are not loaded completely but only their identifiers are loaded. When the application tries to access the associated entity, the ORM kicks in. It loads that entity using its identifier which it had loaded earlier. This is smart because ORM is not guessing when the application needs what. Instead, it is giving the application an ability to fetch on demand what’s needed when.</p><p>Lazy Get is similar. With Lazy Get, you do do not return a linked resource by default. Instead, you return a shallow version with only top level attributes populated. The API consumer can</p><ol><li>Instruct the server to return the linked resources in the same response</li><li>Retrieve the linked resources at a later time using the link returned in the original response</li></ol><p>This is best explained with an example. Let’s say we are building a meetup platform. People can create interest group and host meetups using our platform. Members of the platform can</p><ol><li>Join the groups they like</li><li>Connect with other members of the platform</li><li>RSVP for the events hosted by various groups</li></ol><p>This is a set of basic features any meetup platform can have.</p><p>This platform is API enabled and we have got an API method to retrieve a member resource which looks like below.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3bb66f4baf62d37f1b1ef092ab4226df/href">https://medium.com/media/3bb66f4baf62d37f1b1ef092ab4226df/href</a></iframe><p>For brevity, the above code does not show the full representation of memberships, rsvps and friends resources. In reality, these resources will have more attributes than what I am showing here. They could even have their own linked resources.</p><p>A consumer of this API may not need all of this data all the time. A consumer connecting over LAN would happily accept a lot of data returned. But a mobile app developer connecting over a slow internet connection would not want this. Guess what? You can implement Lazy Get on this API method and let the consumer decide what data they want to be returned. You do this by supporting a new query parameter named expand. This parameter accepts comma separated names of the linked resources that the consumer wants the server to return. So for example, if the URL for retrieving the above member resource was</p><p><a href="https://myapi.com/v1/member/34234">https://myapi.com/v1/member/34234</a></p><p>If a consumer wants only memberships information returned then they can send a request to the following URL</p><pre><a href="https://myapi.com/v1/member/34234?expand=memberships">https://myapi.com/v1/member/34234?expand=memberships</a></pre><p>This is good. Now the consumer has a control over what data server returns. But what happens to other resources i.e. rsvps and friends? Is server just going to exclude them from the response? If server excludes them how does the consumer get those resources when it needs them?</p><p>Instead, what server does is exactly same as what any ORM does with its lazy loading feature. The server returns an identifier of the resource in the place of the full resource.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/b543af784e1af6d8ad7c9ce7e1d5da67/href">https://medium.com/media/b543af784e1af6d8ad7c9ce7e1d5da67/href</a></iframe><p>That way, if the consumer decides to fetch rsvps or friends resources, all they need to do is issue a GET request on the corresponding URLs.</p><h4>Using hypermedia to make this little better</h4><p>In the previous example, how would a client fetch a friend resource with id 5678? Where would it get the actual URL to fetch this resource from?We can use <a href="https://en.wikipedia.org/wiki/HATEOAS">hypermedia</a> to help us here. If you have used hypermedia before then you may have guessed what I am talking about.</p><p>You can use one of the hypermedia specifications like <a href="https://github.com/kevinswiber/siren">Siren</a>, <a href="https://tools.ietf.org/html/draft-kelly-json-hal-08">HAL</a> or <a href="http://amundsen.com/media-types/collection/">Collection+JSON</a> to return actual URL for the resource instead of just the id. If you are still at <a href="https://martinfowler.com/articles/richardsonMaturityModel.html">Richardson Maturity Model — Level 2 or below</a>, don’t worry. You can do what we have done in such cases. We do not return the identifier of the linked resource. For out clients, it does not mean anything. We instead return an attributed href. This attribute contains the URL on which the clients can send a GET request to fetch that resource. The below is how our member resource looks with href attribute returned.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/5b85190009c239b1edec93243c7222e5/href">https://medium.com/media/5b85190009c239b1edec93243c7222e5/href</a></iframe><p>And we return this attribute by default for all our resources.</p><h3>Technique #2: Use a hash API Method to become less chatty</h3><p>Lazy Get is good for controlling the payload size of the response. Would it not be good to not have to make that API call again and again? It is, if the consumer caches the response it received.</p><p>An obvious shortcoming of caching is you would not know when your cache becomes out of date. The server can return cache expiry information in the response headers. The consumer can bust the cache based on this information. But all you are doing here is moving the problem from client to server. The server is still guessing what is the latest time by which the cache must expire. Even worse is that most implementations would set this to a default value.</p><p>Hash API Method offers an alternative for the applications that</p><ol><li>Cannot rely on caching as they always need to work on fresh copy of the data</li><li>Cannot make frequent and heavy API calls due to the environment they operate in i.e. mobile apps.</li></ol><p>A Hash API Method implementation will have the following</p><ol><li>Every resource that needs to support a Hash API Method must include a hash attribute</li><li>The value is of this attribute is the hash of the string (JSON/XML)representation of the resource</li><li>Server recalculates the hash every time the resource state changes.</li><li>A new API method to return the latest hash value for each resource</li></ol><p>Let’s say we want to support hash API method for the member resource from our previous example. So first we add a hash attribute as below</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/f0aa88635ec6f6b6e08980570bb78d90/href">https://medium.com/media/f0aa88635ec6f6b6e08980570bb78d90/href</a></iframe><p>The server uses a mechanism of its own choice to calculate the value of the hash attribute. It could also be a random string. The server must update its value every time the resource state changes.</p><p>Next, we add the following new API method that returns the latest hash value for member resource</p><pre><a href="https://myapi.com/v1/member/%7Bmemberid%7D/hash">https://myapi.com/v1/member/{memberid}/hash</a></pre><p>This API method returns a response with the status of 200 OK. The response body contains the value of the hash attribute of the member resource. The key here is to make this API as fast as possible. The server can cache a map of resource id and hash value to reduce the response time.</p><p>All that a bandwidth-conscious consumer has to do now is to make a call on the Hash API Method. It can then compare the returned hash value with the hash value it has from the previous retrieval of the resource. If the hash values are the same, then it is safe to assume that the resource has not changed since the consumer last retrieved it. If the hash values are different then it’s time to fetch the latest value of the resource.</p><h4>Keeping the hash updated all the times</h4><p>As more and more consumers start using hash API Method, it becomes important to ensure that hashes are always kept updated. This needs proper thinking and optimal design. Consider the following situations</p><ol><li>When a resource gets partially/fully updated, the hash must be updated</li><li>If you hash includes the linked resources, the every time a resource gets updated, all the other resources that link this resource must update their hash.</li><li>When a resource gets deleted, the the hash method for that resource must return a 404 Not Found and every consumer application should handle this response to delete their cached copy of the resource</li></ol><p>If you decide to use Hash API Method, think of about these situations from day 1. Handling these situations as an afterthought can be expensive.</p><h3>Technique #3: Use GraphQL to fetch just what you need</h3><p>GraphQL is a Facebook Open Source project. It started as an idea some years ago but has progressed into a well-defined specification now. There are a handful of libraries for major programming platform that supports GraphQL. As per <a href="http://graphql.org/">GraphQL’s website</a>:</p><blockquote>“GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.”</blockquote><p>This looks similar to Lazy Get, but in reality, it is even more powerful than that. We will see in a bit how. GraphQL also makes it easy to support Hash API Method without having to add a special endpoint. Before we go into these details, let’s look into a quick example of what GraphQL offers.</p><p>If an API consumer needs a shallow copy of member resource without any linked resources then it should send the below GraphQL query</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/c5fcd0e254f0f89880f558e21a522289/href">https://medium.com/media/c5fcd0e254f0f89880f558e21a522289/href</a></iframe><p>Let’s ignore some details like the destination URL for this query and handling of the query on the server. This query returns the specified attributes of the member resource having id 34342.</p><p>If another consumer wants only firstname and lastname then they specify those two attributes in their query. The server will return those attributes. You see how powerful this can be. With Lazy Get, you get all linked resources fully hydrated or none. But it was not possible to strip off some attributes.</p><p>GraphQL’s ability to specify exactly which attributes we want to be returned, lets us support Hash API Method out of the box. A consumer wanting to get the latest value of hash of member resource in the above example would just send the below query</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/17f75ddff3b585c5cef988dd2254d4ba/href">https://medium.com/media/17f75ddff3b585c5cef988dd2254d4ba/href</a></iframe><p>Remember, it is still the same API endpoint on the server that is handling these queries. This gives very granular control to the consumers of the API. Consumers can balance between chunky responses and chatty API calls all by themselves.</p><p><strong>One thing worth mentioning is the performance of the Hash API Method using GraphQL</strong>. A core premise of Hash API Method is that it needs to return as fast as possible. If we have our own implementation of Hash API Method then we have total control to do any fine tuning we need. With GraphQL, we are limited by what the GraphQL library we use offers. If you use GraphQL version of Hash API Method then make sure it is performance tuned for the use case.</p><h4>GraphQL is all about giving control to the consumers of your API</h4><p>I have shown two simple examples of what’s possible with GraphQL. But GraphQL is not limited to simple queries. You can do</p><ol><li>Specify additional filters on attributes like first 10, last 30 or contains</li><li>Specify filters on more than one attribute</li><li>Group commonly returned attributes in <a href="http://facebook.github.io/graphql/#sec-Language.Fragments">fragments</a></li><li><a href="http://facebook.github.io/graphql/#sec-Validation">Query validation</a></li><li><a href="http://facebook.github.io/graphql/#sec-Language.Variables">Parameterize queries</a> using variables</li><li>Dynamically changing query behavior using <a href="http://facebook.github.io/graphql/#sec-Language.Directives">directives</a></li><li><a href="http://facebook.github.io/graphql/#OperationType">Data mutations after fetch</a></li></ol><p>An API that fully supports GraphQL, gives its consumer total control over what data they fetch at what point.</p><h3>Happy API consumer == Happy API developer == Great API</h3><h3>Gartner Events on Twitter</h3><p>Treat your API like a product. Provide a good developer experience and have continuous, proactive engagement with consumers. #GartnerCAT</p><p>One of the ways of providing good developer experience is to give them some control over the APIs that they interact with. Lazy Get, Hash API Method, and GraphQL provide a mechanism by which API developers can give that control to their consumers.</p><p><em>☞ If you like my article, please </em><strong><em>don’t forget to click ❤ to recommend </em></strong><em>it to others.</em></p><p><em>Also, to be notified about my new articles and stories, follow me on </em><a href="https://medium.com/@suhas_chatekar"><em>Medium</em></a><em> and </em><a href="https://twitter.com/suhas_chatekar"><em>Twitter</em></a><em>. You can find me on </em><a href="https://www.linkedin.com/in/chatekar"><em>LinkedIn</em></a><em> as well. Cheers!</em></p><ul><li><a href="https://medium.com/@suhas_chatekar/why-you-should-use-the-recommended-http-methods-in-your-rest-apis-981359828bf7">Why should you use standard HTTP methods while designing REST APIs?</a></li><li><a href="https://medium.com/@suhas_chatekar/visualising-complex-apis-using-api-map-f09f617acb32">Visualising complex APIs using API Map</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=67e60b7bcca7" width="1" height="1" alt=""><hr><p><a href="https://medium.com/free-code-camp/three-ways-to-balance-between-chunkiness-and-chattiness-of-your-rest-api-67e60b7bcca7">How to balance chunkiness against chattiness when designing your REST API</a> was originally published in <a href="https://medium.com/free-code-camp">We’ve moved to freeCodeCamp.org/news</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why should you use standard HTTP methods while designing REST APIs?]]></title>
            <link>https://medium.com/@suhas_chatekar/why-you-should-use-the-recommended-http-methods-in-your-rest-apis-981359828bf7?source=rss-fd0546bc3c39------2</link>
            <guid isPermaLink="false">https://medium.com/p/981359828bf7</guid>
            <category><![CDATA[api]]></category>
            <category><![CDATA[rest]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Suhas Chatekar]]></dc:creator>
            <pubDate>Thu, 09 Feb 2017 23:04:28 GMT</pubDate>
            <atom:updated>2017-02-23T21:23:31.964Z</atom:updated>
            <content:encoded><![CDATA[<p>One of the characteristics of a good REST API is that it uses the standard HTTP methods in a way they are supposed to be used. We hear this all the time and this is the most fundamental guideline of REST. As generally understood, we use the following HTTP methods while designing REST APIs</p><ol><li><strong>GET — </strong>For returning resources</li><li><strong>POST — </strong>For creating a new resource</li><li><strong>PUT — </strong>For updating a resource</li><li><strong>PATCH </strong>— For updating a resource</li><li><strong>DELETE — </strong>For deleting a resource</li></ol><p>But beyond the basics, why is it like that? Isn’t use of two methods, PUT and PATCH for an update operation confusing?</p><h3>What do the specs say?</h3><p>Let’s first get the obvious out of the way. Let’s see what the specs say</p><h4><a href="http://httpwg.org/specs/rfc7231.html#GET">GET</a></h4><blockquote>The GET method requests transfer of a current selected representation for the <a href="http://httpwg.org/specs/rfc7231.html#resources">target resource</a>. GET is the primary mechanism of information retrieval</blockquote><p>What this really means is that you should use GET for an API method that returns the latest version of the resource identified by the API URL.</p><h4><a href="http://httpwg.org/specs/rfc7231.html#POST">POST</a></h4><blockquote>The POST method requests that the <a href="http://httpwg.org/specs/rfc7231.html#resources">target resource</a> process the representation enclosed in the request according to the resource’s own specific semantics.</blockquote><p>This is slightly confusing but that is because POST can be used to do more than one thing — one of which is creating a new resource. This is confusing because if the server can perform more than one operations in response to a request then how do consumers find out what happened exactly? The specification says that the server should make use of one of the 2xx family of status codes to indicate to the client what happened on the server.</p><h4><a href="http://httpwg.org/specs/rfc7231.html#PUT">PUT</a></h4><blockquote>The PUT method requests that the state of the <a href="http://httpwg.org/specs/rfc7231.html#resources">target resource</a> be created or replaced with the state defined by the representation enclosed in the request message payload.</blockquote><p>So PUT can be used to update a resource as well as to create a new resource. That may sound strange at first, but let’s keep things simple for now and trust we should use PUT for an API method that lets consumers update the resource identified by the API URL.</p><h4><a href="http://httpwg.org/specs/rfc7231.html#DELETE">DELETE</a></h4><blockquote>The DELETE method requests that the origin server remove the association between the <a href="http://httpwg.org/specs/rfc7231.html#resources">target resource</a> and its current functionality.</blockquote><p>Again, like POST, DELETE can be used for more than one operations that eventually result in something being removed. Let’s trust we should use DELETE for an API method that let’s consumers delete the resource identified by the API URL.</p><h4><a href="https://tools.ietf.org/html/rfc5789#page-3">PATCH</a></h4><blockquote>The difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the resource identified by the Request-URI. In a PUT request, the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version.</blockquote><p>PATCH, like PUT, should be used for modifying a resource, however, the semantics of modification is performed as slightly different. We will get to this difference in the next section.</p><p>So our original understanding of what each of the HTTP verb means is in line with what the specifications say what they mean. So far so good. Specification tells us in which situations we should we use each verb, but it’s still just a specification. Our implementation can still disregard what the specification tells us to do and have creation of new resources implemented behind a GET operation and deletions implemented a POST operation. However, there are two big benefits to respecting the specification.</p><h3>Idempotence is not limited to mathematics</h3><p>In mathematics, an idempotent operation is one which produces the same result every time it’s performed on the same input. A counter is a good example of this. Operation to “set the counter to 6” is idempotent but the operation to “increment the counter by 1” is not. You see the difference? In the first case, no matter how many times you set the counter to 6, it’s still set to 6 in the end. Whereas, in the second case, if the counter had an initial value of 4 and every time you increment it by 1, the counter gets set to different value.</p><p>Applied to REST, an idempotent operation is the one which does not change the target state of the server. On the other hand, a non-idempotent operation would always change the target state of the server. Notice that we are not talking about state change here but rather the target state of the server. HTTP specification states that GET, PUT and DELETE are idempotent operations. POST and PATCH are non-idempotent operations. “Like earlier, this is just a specification. Why do you need to follow it?” you might ask. Well, there is a reason and a very good one.</p><p>An idempotent operation gives the consumer of the API a guarantee that the state of the server will be the same no matter how many times they call the API. This guarantee is very useful. Imagine that server executes the API method that consumer called successfully but there is an error while sending the response back to the consumer. The consumer ends up getting an error even though the operation has completed successfully on the server. What should the consumer do? Now, if the operation server performed was advertised as idempotent, then consumer can send the request to execute the operation one more time. It can keep doing that as long as it sees a success response without causing server to perform any unwanted state change. On the other hand, if the operation was not advertised as idempotent then consumer would know that it need to check with server before performing the operation again.</p><p>Creation of a new resource is one operation which changes the target state of the server every time it is run with the same inputs leading to a different target state after each execution. Same may apply to deletion of a resource depending on the implementation. Imagine what would happen if we put these operations behind a GET or a PUT verb? A consumer may end up executing these operations multiple times inadvertently affecting the target state of the server negatively. Returning value of a resource, on the other hand, has no impact on the target state of the server and hence should be implemented behind a idempotent verb GET.</p><p>There still is a difference between a PUT and a PATCH. Both are used to modify an existing resource. If you go back to what specification says about PUT you would notice that its similar to saying “set the counter to 6”. PUT is modifications where the consumer provides the target state for the complete resource and instructs the server to replace whatever value the resource has currently with the new value the consumer is sending. No matter how many times the consumer performs this operation, the end state of the resource is never going to change. PATCH on the other hand is similar to “increment the counter by 1”. PUT can be chunky for resources that are large in size and eats away lot of bandwidth. PATCH was introduced to let consumers issue an instruction to the server that tells it how to change a part of the resource. This instruction if executed multiple times could result in an unwanted end state.</p><p>In the end, it’s all down to the implementation but if your implementation respects the specification then the life of your API clients would be lot easier. While we are talking about respecting the specification, there is another interesting characteristics that the specification says all HTTP servers and proxies should build when dealing with HTTP request. Your REST API that respects the specification can make good use of this.</p><h3>Web is fast because of caching</h3><p>Web is probably one of the heaviest users of cache. It not only makes loading of websites faster, it also works so reliably that not making use of it when it’s at our disposal would be foolish. REST uses HTTP and so it should make use of its caching characteristics where possible. <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html">The HTTP cache specification</a> is quite detailed about how it should be implemented by HTTP servers and proxies but I would like to pick two things from the specification that directly apply to REST.</p><ol><li>An operation behind a GET endpoint does not change the target state of the server therefore the response of a GET endpoint can be cached resulting in further requests to the same endpoint being returned faster from the cache</li><li>An endpoint behind PUT, POST, PATCH and DELETE changes the target state of the server therefore a successful response out of any of these endpoints can be used to bust the previously cached responses.</li></ol><p>I know that I am overly simplifying the caching specification of HTTP but this is one of the most elegant caching specification I have come across. And all it takes to take full advantage of this to respect the HTTP specification.</p><p>One last thing about caching that impacts the consumers of an API more than the developers of the API. An API that follows HTTP Cache specification is the most useful to a consumer as long as the consumer uses a HTTP client library that supports caching. I am sure there is at least one such library available for every leading programming platform. So encourage your consumers to use one of those libraries. Having said that, API developers should still make use of caching as HTTP and proxy servers will still cache the responses.</p><h3>In closing</h3><p>Beauty of the HTTP API (and I am intentionally avoiding the word REST here) is that it provides lot of flexibility to the API developer. Any flexibility is a good thing as long as it’s not misused. I have seen many HTTP APIs that either do not make use of recommended HTTP methods or if they do, the developer has little knowledge of why he made those choices. I hope this post throws some light on why we should use recommended HTTP methods.</p><p><em>Thanks to </em><a href="https://medium.com/u/8c2c21ecba8f"><em>Stefan Tilkov</em></a><em>, </em><a href="https://medium.com/u/f6a6cff6c739"><em>Sarang Kulkarni</em></a><em> and </em><a href="https://twitter.com/vrdmn"><em>@vrdmn</em></a><em> for reviewing this story</em></p><p><em>☞ If you like my article, please </em><strong><em>don’t forget to click ❤ to recommend </em></strong><em>it to others.</em></p><p><em>Also, to be notified about my new articles and stories, follow me on </em><a href="https://medium.com/@suhas_chatekar"><em>Medium</em></a><em> and </em><a href="https://twitter.com/suhas_chatekar"><em>Twitter</em></a><em>. You can find me on </em><a href="https://www.linkedin.com/in/chatekar"><em>LinkedIn</em></a><em> as well. Cheers!</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=981359828bf7" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Interfaces or Abstract Classes?]]></title>
            <link>https://medium.com/@suhas_chatekar/interfaces-or-abstract-classes-bce12dce97e?source=rss-fd0546bc3c39------2</link>
            <guid isPermaLink="false">https://medium.com/p/bce12dce97e</guid>
            <category><![CDATA[java]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[csharp]]></category>
            <category><![CDATA[object-oriented]]></category>
            <dc:creator><![CDATA[Suhas Chatekar]]></dc:creator>
            <pubDate>Thu, 09 Feb 2017 22:37:23 GMT</pubDate>
            <atom:updated>2017-02-25T18:32:52.859Z</atom:updated>
            <content:encoded><![CDATA[<p>I have been asking this question in interviews for some years now. I get to hear a lot of interesting answers from folks. All these answers have helped me make a great addition to my knowledge. If you google this topic you would find a lot of interesting articles. <a href="http://msdn.microsoft.com/en-gb/library/vstudio/ms229013(v=vs.100).aspx">This article on MSDN</a> offers a good discussion on the topic. To summarise the recommendations from there and few other articles I have come across, here are the reasons in favour of abstract classes</p><ol><li>Use abstract class if you have a default implementation of some behaviour that child classes do not have to implement</li><li>Prefer abstract classes if your contract has a possibility of changing over time. So if you are using an abstract class and need to add a new method to your abstract class, you can happily add that without breaking any code using that class. Same is not true for interfaces.</li></ol><p>And these are the reasons in favour of interfaces</p><ol><li>Since <em>multiple inheritance</em> is not supported in C#, you cannot inherit your class from two abstract classes. Interface is your only option in such situations.</li><li>If there is no default or common behaviour among all the classes that are inheriting from abstract class then interface may be a better choice.</li></ol><p>I personally do not believe that these give a complete picture.</p><h3>What is wrong with this reasoning?</h3><p>First, above recommendations are mostly around syntax a particular language supports and not around semantics (e.g. use interfaces if you need multiple inheritance). By semantics I mean, what definition of an interface fundamentally differentiates it from an abstract class?</p><p>Second, I feel the above criteria are too futuristic. By that I mean, they all depend on you knowing how your design is going to take shape in future. At times, I may have some idea of how my design is going to take shape in future but most of the times I do not have enough clarity to know in advance</p><ol><li>Whether I am going to need to inherit from multiple abstract classes or not</li><li>Whether there is going to be a default implementation of some contract or not</li><li>Whether I would add a new method to a contract or define a new contract entirely in order to implement a change</li></ol><p>So, if you do not know which way your software is going to go, there is no way you can base your decision of <em>interface or abstract class</em> on these reasons.</p><h4>So what is the option?</h4><p>Lately, I have been using below heuristic to determine when to use interfaces/abstract classes and I feel quite excited about it as it works most of the time.</p><blockquote><em>Interfaces represent capabilities and abstract classes represent type</em></blockquote><p>in other words</p><blockquote><em>Implementing interfaces represents </em><strong><em>can-do</em></strong><em> relationship and inheriting from (abstract) class represents an </em><em>is-a relationship</em></blockquote><p>To elaborate this point, let’s consider following two classes</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/fd56998b7531ea558697279378093b81/href">https://medium.com/media/fd56998b7531ea558697279378093b81/href</a></iframe><p>Both Camera and Gun can Shoot, that is their capability. But they are both not the same type of things, they are completely different. So an interface like below would make more sense here</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/d3aaa570dcf9645a87dd9947cbce551e/href">https://medium.com/media/d3aaa570dcf9645a87dd9947cbce551e/href</a></iframe><p>If you have learned OO programming the same way I did, then you would remember the classic shape example as below</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/fe027a5ea718708395b8261d67d4c4a8/href">https://medium.com/media/fe027a5ea718708395b8261d67d4c4a8/href</a></iframe><p>Rectangle and Circle inheriting from Shape makes perfect sense here becauseRectangle/Circle are a type of Shape.</p><h4>In closing</h4><p>As your software grows and new features start pouring in, old features keep changing, you would hit a point where you would say to yourself “<em>Oh</em> <em>God, I should not have used an abstract class here”</em>. Instead of trying to predict feature about who will reuse which code, focus on determining whether it is a capability that you are abstracting away or a common type. If you find that line of thinking difficult, then work out if it is a <em>can-do </em>relationship that you are trying to model or an <em>is-a</em> relationship.</p><p><em>☞ If you like my article, please </em><strong><em>don’t forget to click ❤ to recommend </em></strong><em>it to others.</em></p><p><em>Also, to be notified about my new articles and stories, follow me on </em><a href="https://medium.com/@suhas_chatekar"><em>Medium</em></a><em> and </em><a href="https://twitter.com/suhas_chatekar"><em>Twitter</em></a><em>. You can find me on </em><a href="https://www.linkedin.com/in/chatekar"><em>LinkedIn</em></a><em> as well. Cheers!</em></p><p><em>Originally published at </em><a href="http://blog.chatekar.com/interfaces-or-abstract-classes/"><em>blog.chatekar.com</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bce12dce97e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Visualising complex APIs using API Map]]></title>
            <link>https://medium.com/@suhas_chatekar/visualising-complex-apis-using-api-map-f09f617acb32?source=rss-fd0546bc3c39------2</link>
            <guid isPermaLink="false">https://medium.com/p/f09f617acb32</guid>
            <category><![CDATA[raml]]></category>
            <category><![CDATA[rest-api]]></category>
            <category><![CDATA[swagger]]></category>
            <category><![CDATA[api]]></category>
            <dc:creator><![CDATA[Suhas Chatekar]]></dc:creator>
            <pubDate>Sat, 04 Feb 2017 10:49:08 GMT</pubDate>
            <atom:updated>2019-05-08T22:18:26.786Z</atom:updated>
            <content:encoded><![CDATA[<p><strong><em>A picture is worth a thousand words…</em></strong></p><p>That is one of the reasons why we like to represent the most complex ideas of software through pictures and diagrams. Class and sequence diagrams are most commonly understood but there are a large number of diagrammatic representations of various software and architectural concepts that have grown over time. A diagram generally provides an easy to digest overview of complex software architecture. In my experience, this forms a foundation of understanding that greatly helps while getting to understand that architecture in detail. Like most people, I really like this approach. One area where I have struggled to do this and is forced to go straight into low-level details is API documentation. When we want to consume a new API, we are usually given an API spec. Most likely this spec is written in <a href="http://swagger.io/">Swagger</a> which does a good job is describing low-level details of what each endpoint in the API does. This works quite well for very simple APIs. But the moment the complexity of APIs grows, I crave for that basic understanding of the API that makes diving into the details a bearable process.</p><p>Recently, I tried to address this by putting out an overview diagram for the APIs that my team delivered. I call this <strong>API Map</strong>. I took inspiration from class diagram as it nicely answers the questions that I usually have when I see API specs that are beyond simple.</p><p>1. What are all the resources that this API exposes?</p><p>2. How are the resources related to each other?</p><p>3. How do I perform important operations on key resources?</p><p>As you may have guessed, the API map centres around <strong>resource</strong>, a core tenet of REST. Diagrammatic representation I used for a resource is very close to a class with a few obvious differences.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/466/1*lbAqxNJ10LFPVk6uOFVfOw.png" /><figcaption>Skeleton of a resource representation in an API Map</figcaption></figure><p>It has got a <strong>resource name</strong> and <strong>resource description. </strong>This can be copied from your API specs for the sake of consistency. Then it lists all the endpoints around that resource grouped by four main HTTP verbs we use in REST APIs — <strong>GET, POST, PUT </strong>and<strong> DELETE. </strong>This is not prescriptive. If a resource does not have any DELETE endpoint then I would not have a DELETE section on my diagram. Similarly, if you use other HTTP verbs then feel free to add them. Next, to the verb, we mention endpoint URLs that correspond to that verb. This is a free text field with no prescribed way of how we provide this information. We can be as creative as we want here.</p><p>Let’s use an example API for a library. That’s simple enough for a blog post. In a simple library API, you would have books, authors, members and their rentals. A book resource in an API map can look like the below.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/689/1*VBViREMwS9BzXasUsy-jvA.png" /><figcaption>Representation of book resource in API Map</figcaption></figure><p>This is a very standard CRUD API. There is more than one way to get a book which is all listed. An interesting one is to get all the books written by an author. We will visit this endpoint again in the next section about relations. This endpoint is captured under book resource as the endpoint returns a list of books.</p><p>Let’s look at relations next. There is a bi-directional relation between a book and an author. A book has one or more authors. An author has one or more books. Let’s say, we have decided not to support the bi-directional relation in our APIs. We only support “the author has one or more books” relation. This relation is embodied into the endpoint <strong>/author/{id}/books </strong>which returns all the books written by the author having specified id. This is listed under book resource as it returns a list of books. However, without a visual aid, finding out such relations by scanning all the endpoints on a relatively bigger API map is challenging. So we use lines with arrows and text to represent such relation.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tEoOS68OqT0kiSNeUq1rAA.png" /><figcaption>The relation between two resources represented visually in an API Map</figcaption></figure><p>Instead of drawing a random line from one resource to another, we draw them as close to the endpoint in question as possible. This makes it easy to find out which endpoint represents that relationship.</p><blockquote><em>The author endpoint could be modelled entirely differently. For example, you may never expose an endpoint to add authors explicitly because they are automatically when a book is added. Same applies to deleting authors.</em></blockquote><p>That’s it really. This is how a complete API map for our simple library API looks like.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RGvKz_Sa2naMGASB13Ktvg.png" /></figure><p>Sometimes there is indirect relation between two resources. In our example, members have an indirect relation to books when they rent books. This relation is via a rental resource. If it is worth highlighting the indirect relation then we use a dotted line to represent it with all other conventions being the same.</p><h3>Is this not just an ER diagram for APIs?</h3><p>I will not blame you if you felt that this is just an ER diagram for APIs. The simple library example with mostly CRUD-like API Methods is partly to blame. However, if your API is designed to be CRUD-like then your API Map will look similar to an ER diagram. This is still a good thing because the API Map is bringing to the surface the fact that the API is designed like that, intentionally or unintentionally. But back to the original question — is API Map really just an ER diagram for the API? Think of the following</p><ul><li>An ER diagram describes the structure of the tables. API Map does not focus on the structure of the resources.</li><li>The only relation between entities that an ER diagram describes is that of cardinality. In an API Map, in addition to cardinality, you can use rich relation descriptor as it’s just a free text.</li><li>In a traditional sense, an ER diagram is a design tool. You would design your databases using an ER diagram and then build the actual DDL scripts from it unless you auto-generated your DDL using an ORM. API Map is not a design tool. It merely describes an API after it is implemented.</li><li>An ER diagram documents the structure of entities and relations between them but does not talk about how you can interact with those entities e.g. via stored procedures, functions and triggers. API Map, on the other hand, emphasises on API methods through which consumers interact with the resources. As an API consumer if you cannot access or modify a resource via one of the described API methods then you cannot access or modify that resource.</li></ul><p>API diagram has some similarities to ER diagram but its intention is very different from that of an ER diagram. Having said that, It would be useful to take some inspiration from an ER diagram to enhance API Map. We can use standard cardinality notations from ER diagram if that helps. If you believe it will help to include important attributes on the resources in an API Map, the way ER diagram does, feel free to do that too. I don’t think it&#39;s about whether API Map is just an ER diagram or not. It’s about what value does API Map add and in my opinion, it does add value.</p><h3><strong>In closing</strong></h3><p>This still has some gaps, however, it has tremendously helped me introduce complex APIs to new developers in a gentler way. I usually show new developers an API map before I throw them into complex swagger specs. The only challenge I have faced so far is that drawing this diagram up can be time-consuming if you try to use standard diagramming tools. You would need to resize and move shapes around in order to fit all the text and stack the shapes next to each other nicely. Visio does a great job at this and is my tool of choice. A hand drawing should also do a good judgement of this diagram.</p><p>What do you use to visually represent your APIs? Let me know via comments.</p><p><em>☞ If you like my article, please </em><strong><em>don’t forget to click ❤ to recommend </em></strong><em>it to others.</em></p><p><em>Also, to be notified about my new articles and stories, follow me on </em><a href="https://medium.com/@suhas_chatekar"><em>Medium</em></a><em> and </em><a href="https://twitter.com/suhas_chatekar"><em>Twitter</em></a><em>. You can find me on </em><a href="https://www.linkedin.com/in/chatekar"><em>LinkedIn</em></a><em> as well. Cheers!</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f09f617acb32" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Who owns my card transactions?]]></title>
            <link>https://medium.com/@suhas_chatekar/who-owns-my-card-transactions-57f62d3023fa?source=rss-fd0546bc3c39------2</link>
            <guid isPermaLink="false">https://medium.com/p/57f62d3023fa</guid>
            <category><![CDATA[startup]]></category>
            <category><![CDATA[finance]]></category>
            <category><![CDATA[ideas]]></category>
            <dc:creator><![CDATA[Suhas Chatekar]]></dc:creator>
            <pubDate>Thu, 03 Dec 2015 17:30:33 GMT</pubDate>
            <atom:updated>2015-12-03T17:30:33.751Z</atom:updated>
            <content:encoded><![CDATA[<p>Someone on Quora asked <a href="https://en.wikipedia.org/wiki/Vinod_Khosla">Vinod Khosla</a>, what he thinks of BitCoints. While that is not relevant to what I am talking about, but he made an interesting point. Finance is the biggest business sector right now and it is unfair. The real businesses that provide real services that we use daily are not the biggest businesses. Blockchain, the technology that powers BitCoins, Khosla believes, has power to change this.</p><p>There are lot of streams of revenues for the companies operating in finance sector. One of the streams of revenues for banks and card networks is selling card transactions data to other businesses. This is obviously not illegal and most companies would do this with an implicit consent of the card holder. But for businesses which want access to this data, it is an expensive affair. Card transactions is probably one of the most important piece of data in today’s times. Innovative start-ups can build really amazing products around it if this data is made available without friction and in a cost-effective way. But this data is locked down into legacy systems of banks and card networks and getting this data out means you have to hefty fees which early stage start up cannot offer.</p><h4>A facebook like model</h4><p>What is we turn the tables and make the card holder the legal owner of all her card transactions? Think of this like facebook. Stuff I post of facebook, people I connect to, it all belongs to me. Facebook stores it on their servers, they use to make facebook work, they even sell anonymised data about me to run their advertising platform. But no one has access to my posts, friend list without my explicit permission.</p><p>Similarly, all my card transactions can be stored by banks or card networks, they can use those to fulfil their functions, can sell anonymised transactions but they need to give my transactions freely to businesses that I trust. For start-ups, this makes it very easy to get access to card transactions to build those innovative products not available in the market today. All they need to do is ask for card holder’s permission to access their transactions. And card holder’s can always revoke access if they do not trust a business with their transactions.</p><h4>What’s in it for card holders?</h4><p>I personally feel that the way data driven research, machine learning and predictive analytics is heading, there is a huge chance to build better financial applications for every day use. I am not talking about systems that help businesses profile people based on their spend and then target advertisements. I am talking about systems that would look at my spend and help me better manage my money using best of breed data crunching technology that is available today. And as a use, I should have freedom to decide who crunches my card data. I do not want my bank to decide that for me.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=57f62d3023fa" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>