If you are POSTing to an endpoint and applying retries, you want that operation to be idempotent. Scott Hanselman that mentions this specific issue:Ī few things to remember. Different endpoints are going to have different needs, and most importantly: POST is not idempotent, so applying retries are going to wreak havoc when the developer encounters their first failed POST call.Īfter hitting that, a user may realize their error and search along the lines of 'polly httpclient (idempotent OR idempotency)' on the upstream docs or Microsoft docs and promptly come up with no results.īroaden the search results to any website and the top post is a helpful from Scott Hanselman However, the first real-world problem a user is going to run into is going to be needing multiple policies. It shows building blocks - how to add a policy to a HttpClient instance, and how to select policies. Luckily, there's a whole docs page for that! It'll even (briefly) touch upon that socket exhaustion gotcha with HttpClient. Say you want to make REST API calls to an external dependency, and want to also use Polly to add resiliency those calls. NET implementation details warrants additional verification on top of the X.509 class methods. You'll probably end up implementing HttpClient in the obvious but sub-optimal way that causes socket exhaustion, or be lulled into a false sense of security from X509Chain.Build() without realizing nuance in the. That's a great way to have users to shoot themselves in the foot, instead of guiding users the right direction.įor example, if you are deeply experienced in the C#/.NET ecosystem and patterns, you probably already have an idea of what classes need to interact together to achieve the desired behavior and the patterns necessary to avoid gotchas down the line - it's extensive and wonderful, in-depth API docs are perfect for you!īut if you are a developer reading the docs with a fresh eye, trying to figure out " how do I issue HTTP GET in C#?" or " how to I verify a self-signed X.509 certificate with. It assumes they know about how the parts of your project are supposed to interact, within itself or with the language's standard library. Very specific API documentation best helps the former, while good examples and detailed remarks help the latter.ĪPI documentation does little to help the latter group. People who are trying to figure out how to achieve specific desired behavior, are new to your project, and seeing if the fit is right.People who have used your project before, and just need a refresher on API surface area.Readers of documentation will generally fall into two buckets: Writing quality documentation is about knowing your audience. It leaves users to stumble through assembling pieces to solve their scenario the hard way - akin to if a LEGO instruction booklet listed only all the different ways in which each LEGO shape could be used, but contained no step-by-step assembly instructions. They are after desired behavior, and your class' API surface area is the afterthought.Ī big gripe I have with documentation - in particular that of C#/.NET - is how often it falls into the trap of documenting the usage of specific methods or class basic building blocks without documenting the broader interactions, resulting in a myopic view of the overall desired behavior a developer is after. Developers are not trying to problem-solve how to use your class' API, they're problem-solving for scenarios. it's probably not that helpful to the people who need it most. Technical documentation sets will typically show you documentation for class API surface areas, maybe auto-generated from source comments. It doesn’t preclude having different ways of doing things, but there should be one obvious way. It will try to handle all the 'gotchas' for you in a reasonable manner, and only if you want to customize it do you need to check the API docs. It means Python library and modules often have one, clear, canonical way to do things and that implementation will typically have a 5-10 line sample that will cover user needs 99% of the time. It explicitly calls out: there should be one- and preferably only one -obvious way to do it. I like Python so much because the developer experience working is amazing - it's an incredibly productive language because of the Zen of Python.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |