How to make a Public API to be used
In the frontend, OpenSource almost completely reigns, and more recently the component approach is gaining popularity. It seems to be all wonderful. For small companies, the component approach helps to reuse the code, and for large companies to align the UX in the entire product line, services and other things. And here we are all such wonderful cool developers sawing our frameworks, libraries and widgets, happily believing that if they solve our problems, then they solve the problems of the surrounding world. We post them in public, waiting for grateful users, stars on GitHub, downloads on NPM. But for some reason some libraries take off, while others go unnoticed and forgotten.
Why is this happening. Surely it happened that when you were looking for a library with the necessary functionality or the same NPM package, you found something like this:
')
Essentially just a piece of code. Without any explanation of what it is, what it does, how to use it. If this is an NPM packet, then you can probably get into his gut, understand how it works, and use it at your own risk. But if this is a service, then nothing can be done about it - after all, you will not find out what methods he has and what data they expect at the entrance.
What do we expect to see when we find some public API? Probably something like this:
This is NPM from Babel. It tells you what it is, what it does and how to use it. That is, when we put something in public access, we have to attach documentation. Otherwise, it is simply meaningless.
In the frontend, frameworks and libraries appear almost every day, so now it has become very popular to provide them with a landing page as well.
In essence, this is advertising, in which they tell us what problem this API solves, than it is cooler than its competitors, why you should definitely use it, even if you don’t need it and stuff like that. And already from this landing page there are links to documentation, which usually has sections Getting Started and API Reference .
Getting Started is a section for users who see your API for the first time. This section describes where to download, how to build, how to run and the like. It is also customary to describe how to use the various functions of the product. For example, we are in APS, in Getting Started we take a small application and step by step add various functionality to it, bringing up a full-fledged combat solution by which you can already make some of your own applications.
API Reference is designed for advanced users who know how to use your API and just want to clarify the name of a property or parameters of a method.
It may seem that the documentation is difficult and expensive, because it needs to be kept up to date, but this, fortunately, is a bit wrong. I hope that you all love yourself and write code with comments. Most likely, you describe your modules and methods in JSDoc format, well, simply because it is the de facto standard in the industry. And if you use React, then you have data-props. There are many utilities that can build JSDocs according to your code and issue JSON dictionaries that can be displayed by various viewers as you like, that is, with sorting, searching, highlighting, categorization and everything else. With TypeScript they say everything is fine too.
Any documentation should have examples. And it is very important to ensure that they work. Nothing spoils the impression of the project, as immediately non-working examples from the documentation. Surprisingly, this does not happen as rarely as one might think.
Well, we have examples, it seems to us that we helped people. But usually people want to play around with themselves, experiment, that is, they want to understand for themselves whether it is possible to do something from these examples that solves their tasks. And they want to do it quickly, simply, without downloading or installing anything. And this is also a solvable task, because we are JavaScript developers, we can almost run everything in the browser, and we have our wonderful sandboxes a long time ago: codepen , jsfiddle , jsbin . You can build your small snippet using your API and add a link to the documentation on which people will immediately go and experiment.
You may become cramped in the public sandbox and you want to make your own. This is also not so difficult, because we have two wonderful libraries of code editors in the browser. The first is CodeMirror , it is used, for example, in jsfiddle and Firefox DevTools. The second is Ace , it is used in Atom, by many loved ones. We in the APS didn’t become petty and made our own public sandbox , just using CodeMirror.
Initially, we expected that the beginner would use the sandbox, so we made it so that any examples from the documentation can be opened in the sandbox, and we also immediately added code completion. And in this, too, there is no rocket Sains, because we have JSON dictionaries of our API and we can simply feed them to the code editor. And this can be done not only with browser editors. For example, I managed to get such code completion in Sublime. Later we added the choice of API version, simultaneous work of several users with one code fragment and so on, but these are all optional ryushechki. The main thing is that it is not at all difficult to make a simple sandbox with a code editor and results in an Iframe. And again, for React there is already a ready generator of such sandboxes.
So we did the documentation, made the sandbox, and it seems that we can stop there. True, but only if you are going to stop developing your API. If you want to develop it further, it is better to interact with your users. And face to face, rather than throwing them new functionality through the wall as high as possible so as not to hear their "grateful" shouts. The easiest way to do this is with the help of any issues on GitHub or various chats and channels in the messengers. But there are things that users will not tell you. For example, a person had a problem, he somehow solved it, even let it go with a crutch, and he lovingly carries ctrl-c / ctrl-v from a project to a project with this crutch. But it may turn out that you didn’t foresee such a scenario, and in the worst case, the user could even get into some of your private API. How to deal with this?
The first way is to collect various metrics, that is, to log method calls and send them somewhere. You can keep track of which modules and widgets were created, with what parameters and the like. Of course, you also need to track the environment in which your code was executed (browser versions, mobile devices), because statistics on the use of browsers in the world is useful, but your users may be stylish / fashionable / youth who use only modern browsers, and for some reason you are wasting time and effort on supporting IE.
The second way of interaction is more suitable for large companies that are interested in using their public API - to set up special training teams. Remember how Yandex to us all the brain picked with his BEM at various subbotniki and mitapah? We at Odin also have a team of coaches who ride around the world and train APS people. In the classroom, coaches see where people have the most difficulty, where they insert crutches, lovingly transferred from project to project, then we carefully pave these paths trodden by people and make them comfortable roads.
Well, we have established user interaction, change the API as they ask, make it better, better ... And here we are in for a mine, which is called backward compatibility. Imagine you quietly sleeping peacefully at home or basking on a paradise island on vacation, and then the boss calls and shouts that everything is gone, everything is broken, the server is lying, customers are leaving, plaster is being removed, do something.
You start to remember and understand that nothing has changed there for a month. Climbing to understand - it turns out, there is some kind of small library updated the minor version, and the one who supports it, decided that method A does not do what is necessary, and changed his behavior. But you expected from the method of the old behavior. And your code was expecting old behavior. If you behave as the owner of this library, you will very quickly lose all users.
How to deal with this?
I can not offer anything original here: only tests, tests and tests again. Moreover, the tests are not just to cover the code, but to cover the public API. We in Odin, approached this completely totalitarian and check at the stage of a pull-request, firstly, the degradation of the line of coverage, and, secondly, the degradation of the public API. Since we have JSON dictionaries, we can match them with the coverage report and find out which methods were not covered by the tests. If such ones appear, then the check is considered not passed and such a pull-request cannot be combined with the master branch.
What needs to be done to make the public API enjoyable?
First, write the documentation . To lay out anything in public access without documentation is at least silly, because no one will use it. And with the documentation there is an interesting life hack. Ask new colleagues who are not familiar with your API to do something with it in your documentation. Because when you read the documentation, you “impose” it on the knowledge of the API device and you understand everything. And a new person doesn’t have such knowledge, he does it strictly according to the documentation and, as practice shows, he necessarily finds some shoals. As a bonus, he joins the work already having some idea what you are doing here and why all this is necessary.
Secondly, you need to interact with users in order not to make a spherical horse in a vacuum.
And thirdly, you need to write tests . Moreover, pouring all the three-meter layer of concrete, completely controlling any changes, that is, so that the public API changes only when the major version changes.
Why is this happening. Surely it happened that when you were looking for a library with the necessary functionality or the same NPM package, you found something like this:
')
Essentially just a piece of code. Without any explanation of what it is, what it does, how to use it. If this is an NPM packet, then you can probably get into his gut, understand how it works, and use it at your own risk. But if this is a service, then nothing can be done about it - after all, you will not find out what methods he has and what data they expect at the entrance.
What do we expect to see when we find some public API? Probably something like this:
This is NPM from Babel. It tells you what it is, what it does and how to use it. That is, when we put something in public access, we have to attach documentation. Otherwise, it is simply meaningless.
Documentation
In the frontend, frameworks and libraries appear almost every day, so now it has become very popular to provide them with a landing page as well.
In essence, this is advertising, in which they tell us what problem this API solves, than it is cooler than its competitors, why you should definitely use it, even if you don’t need it and stuff like that. And already from this landing page there are links to documentation, which usually has sections Getting Started and API Reference .
Getting Started is a section for users who see your API for the first time. This section describes where to download, how to build, how to run and the like. It is also customary to describe how to use the various functions of the product. For example, we are in APS, in Getting Started we take a small application and step by step add various functionality to it, bringing up a full-fledged combat solution by which you can already make some of your own applications.
API Reference is designed for advanced users who know how to use your API and just want to clarify the name of a property or parameters of a method.
It may seem that the documentation is difficult and expensive, because it needs to be kept up to date, but this, fortunately, is a bit wrong. I hope that you all love yourself and write code with comments. Most likely, you describe your modules and methods in JSDoc format, well, simply because it is the de facto standard in the industry. And if you use React, then you have data-props. There are many utilities that can build JSDocs according to your code and issue JSON dictionaries that can be displayed by various viewers as you like, that is, with sorting, searching, highlighting, categorization and everything else. With TypeScript they say everything is fine too.
Any documentation should have examples. And it is very important to ensure that they work. Nothing spoils the impression of the project, as immediately non-working examples from the documentation. Surprisingly, this does not happen as rarely as one might think.
Sandbox
Well, we have examples, it seems to us that we helped people. But usually people want to play around with themselves, experiment, that is, they want to understand for themselves whether it is possible to do something from these examples that solves their tasks. And they want to do it quickly, simply, without downloading or installing anything. And this is also a solvable task, because we are JavaScript developers, we can almost run everything in the browser, and we have our wonderful sandboxes a long time ago: codepen , jsfiddle , jsbin . You can build your small snippet using your API and add a link to the documentation on which people will immediately go and experiment.
You may become cramped in the public sandbox and you want to make your own. This is also not so difficult, because we have two wonderful libraries of code editors in the browser. The first is CodeMirror , it is used, for example, in jsfiddle and Firefox DevTools. The second is Ace , it is used in Atom, by many loved ones. We in the APS didn’t become petty and made our own public sandbox , just using CodeMirror.
Initially, we expected that the beginner would use the sandbox, so we made it so that any examples from the documentation can be opened in the sandbox, and we also immediately added code completion. And in this, too, there is no rocket Sains, because we have JSON dictionaries of our API and we can simply feed them to the code editor. And this can be done not only with browser editors. For example, I managed to get such code completion in Sublime. Later we added the choice of API version, simultaneous work of several users with one code fragment and so on, but these are all optional ryushechki. The main thing is that it is not at all difficult to make a simple sandbox with a code editor and results in an Iframe. And again, for React there is already a ready generator of such sandboxes.
User interaction
So we did the documentation, made the sandbox, and it seems that we can stop there. True, but only if you are going to stop developing your API. If you want to develop it further, it is better to interact with your users. And face to face, rather than throwing them new functionality through the wall as high as possible so as not to hear their "grateful" shouts. The easiest way to do this is with the help of any issues on GitHub or various chats and channels in the messengers. But there are things that users will not tell you. For example, a person had a problem, he somehow solved it, even let it go with a crutch, and he lovingly carries ctrl-c / ctrl-v from a project to a project with this crutch. But it may turn out that you didn’t foresee such a scenario, and in the worst case, the user could even get into some of your private API. How to deal with this?
The first way is to collect various metrics, that is, to log method calls and send them somewhere. You can keep track of which modules and widgets were created, with what parameters and the like. Of course, you also need to track the environment in which your code was executed (browser versions, mobile devices), because statistics on the use of browsers in the world is useful, but your users may be stylish / fashionable / youth who use only modern browsers, and for some reason you are wasting time and effort on supporting IE.
The second way of interaction is more suitable for large companies that are interested in using their public API - to set up special training teams. Remember how Yandex to us all the brain picked with his BEM at various subbotniki and mitapah? We at Odin also have a team of coaches who ride around the world and train APS people. In the classroom, coaches see where people have the most difficulty, where they insert crutches, lovingly transferred from project to project, then we carefully pave these paths trodden by people and make them comfortable roads.
backward compatibility
Well, we have established user interaction, change the API as they ask, make it better, better ... And here we are in for a mine, which is called backward compatibility. Imagine you quietly sleeping peacefully at home or basking on a paradise island on vacation, and then the boss calls and shouts that everything is gone, everything is broken, the server is lying, customers are leaving, plaster is being removed, do something.
You start to remember and understand that nothing has changed there for a month. Climbing to understand - it turns out, there is some kind of small library updated the minor version, and the one who supports it, decided that method A does not do what is necessary, and changed his behavior. But you expected from the method of the old behavior. And your code was expecting old behavior. If you behave as the owner of this library, you will very quickly lose all users.
How to deal with this?
I can not offer anything original here: only tests, tests and tests again. Moreover, the tests are not just to cover the code, but to cover the public API. We in Odin, approached this completely totalitarian and check at the stage of a pull-request, firstly, the degradation of the line of coverage, and, secondly, the degradation of the public API. Since we have JSON dictionaries, we can match them with the coverage report and find out which methods were not covered by the tests. If such ones appear, then the check is considered not passed and such a pull-request cannot be combined with the master branch.
Total
What needs to be done to make the public API enjoyable?
First, write the documentation . To lay out anything in public access without documentation is at least silly, because no one will use it. And with the documentation there is an interesting life hack. Ask new colleagues who are not familiar with your API to do something with it in your documentation. Because when you read the documentation, you “impose” it on the knowledge of the API device and you understand everything. And a new person doesn’t have such knowledge, he does it strictly according to the documentation and, as practice shows, he necessarily finds some shoals. As a bonus, he joins the work already having some idea what you are doing here and why all this is necessary.
Secondly, you need to interact with users in order not to make a spherical horse in a vacuum.
And thirdly, you need to write tests . Moreover, pouring all the three-meter layer of concrete, completely controlling any changes, that is, so that the public API changes only when the major version changes.
Source: https://habr.com/ru/post/340524/
All Articles