Amazon API Gateway – Build and Run Scalable Application Backends
aws.amazon.com
aws.amazon.com
On the other side it seems like other extra functionality is limited and very AWS-oriented. If you are looking for an open source gateway that can be expanded with extra functionality, and potentially sit on top of the AWS-> Lambda integration, take a look at https://github.com/Mashape/kong (I am a core maintainer too, so feel free to ask me any question). Kong is accepting plugins from the community (http://getkong.org/plugins), which can be used to replace or extend functionality beyond any other gateway including AWS Gateway.
It's in legacy API services that places like Mashery and Apigee make all their real money, and I can't see large enterprises shifting their legacy services to EC2. It's quite forward looking. The satire on how EC2 may be deprecated is really not far off from where things are heading.
I always find it quite funny when only single OSS projects are mentioned as alternatives, there's so many more full-featured projects out there: Tyk (https://tyk.io) API Umbrella (http://apiumbrella.io/) and ApiAxle (http://apiaxle.com/) to name some. For more fine grained approaches there's also Vulcan (http://vulcanproxy.com/)
The SOAP to JSON conversion is easy for baby SOAP or JSON requests using transformation. For larger ones they turned out to be complex.
Once you start with client started with using the "SOAP" converted to JSON apis, there were new feature kind of requests. Now the problem is somebody needs to be dig into that old code mess of SOAP web services. Or write new services and split requests between old and new services.
There will be performance issues because of the no of transformation doing on top of the request. Ultimately has to write plugins on top write performant transformation in a single piece.
Personally SOAP to JSON conversion will not be as simple as move to AWS, although I will assume Amazon will do far far better job on this than others.
vulcan is not for api management and beside that quality > quantity
Also, how can you gracefully reload kong if you need to add/remove/change a plugin ? With vulcand you just replace the binary, and send an USR2 signal to the running process. It will fork, wait for all connections to drain, and remove the old process
For deployment, again, you need to sync all lua files, with vulcand you just ship a compiled binary.
Kong doesn't have a notion of servers for each API, you need to forward requests to a haproxy or another load balancer for this. Also, I can see that backends are added by their DNS hostname. In order to achieve HA (backend redundancy) is there any way you can do it, assuming that nginx is caching the upstream dns values ?
About performance, I can see you are advertising about 1000 r/s using kong, and you need 3 machines for this (kong, cassandra, haproxy). I benchmarked vulcand and obtained about 12000 r/s on a more modest hardware.
Nginx is not an API management layer, right? It doesn't have the necessary features, but it's extensible so someone could build them. Mashape did, and they released the result as Kong.
Vulcand is in the same position as nginx. It could be a good choice for building an API management layer on, but it doesn't provide one out of the box.
> How can you gracefully reload kong if you need to add/remove/change a plugin?
You can gracefully reload Kong by executing "kong reload" (http://getkong.org/docs/0.3.2/cli/#reload). It pretty much works the same way: fork, wait for existing connections to drain, and remove the old master process.
> For deployment, again, you need to sync all lua files, with vulcand you just ship a compiled binary.
Kong has a few distribution options (rpm, deb, Docker, etc) that simplify the process (http://getkong.org/download/), so unless it's being built from source, the deployment is straightforward.
> Kong doesn't have a notion of servers for each API, you need to forward requests to a haproxy or another load balancer for this. Also, I can see that backends are added by their DNS hostname. In order to achieve HA (backend redundancy) is there any way you can do it, assuming that nginx is caching the upstream dns values ?
You are correct. Kong supports either a DNS or IP address for a backend service, and starting from 0.5.0 it will be possible to add more DNS addresses or IPs per each API. That will make Kong work in load-balancing mode (https://github.com/Mashape/kong/issues/157).
> About performance, I can see you are advertising about 1000 r/s using kong
Kong is basically built on top of nginx (a very solid core), and it can achieve a similar performance to nginx because all the data requested from the external datastore is being cached in memory. So pretty much the latency it's going to be nginx + Lua execution overhead (which is minimal, thanks to LuaJIT). I will run a better benchmark and write a blog post soon, trying to cover both single-node and multi-datacenter setups.
> and you need 3 machines for this (kong, cassandra, haproxy)
An external datastore (Cassandra - with plans to support PostgreSQL) is required because Kong has been built to scale multi-node and multi-datacenter in order to handle pretty much every use case and plugin/middleware. In very simple single-node use cases, Cassandra can live in the same instance along with Kong. I would say that in this regard Kong is inspired by a different philosophy (start small, grow big, even supporting hybrid cloud/bare-metal setups). Having an external datastore also means that Kong could support some pretty cool plugins, like multi-datacenter service discovery, API billing coordination, multi-region health checks, etc. For example today it is possible to rate-limit requests in an eventually consistent replication fashion across multiple data-centers.
[1] http://www.meetup.com/The-Mashape-API-Developer-Community/ev...
any plans to add pluggable backend ie not use cassandra? i've no experience managing cassandra and would rather not worry about it.
For testing check out http://kongdb.org/, but don't use it in production.
I've got an API already running. What does this buy me?
Caching? I can see some benefit there it's read heavy.
Auth and access control? Feels like that's part of my app code but maybe there's a benefit I'm missing
A lot of the other benefits also feel like it would be hard to cleanly separate them from my app code.
What's the elevator pitch and who's the target market?
Imagine this: You are BigCorp USA Inc. and have a bunch of internal SOAP-based web services that are 10 years old and cost a fortune to maintain.
You hear someone will pay you to use them, but SOAP sucks. So you could either go and change your APIs (and probably break a bunch of internal processes) OR you could use a gateway to sit in front of them and translate in bound / outbound requests. Now you can charge people for your APIs!
Scenario 2: If you're an indie dev/ startup but dont want to run EC2 infrastructure, Lambda + Gateway = Cloud service, without any heavy lifting, servers and cost effective. It's development lego. Kind of like Parse.
Scenario 3: You have an API for your app, now you wnat third party devs to use it.Your API is not set up for that kind of access (multi-user security, throttling, quotas, analytics etc.) - solution: shove a gateway in front of it.
How do you go about proxying REST style requests to a SOAP backend?
A harder case is when you have a "service" layer which also has a large collection of queries at various levels of abstraction.
These map poorly into resources, where you want a single level of abstraction per resource. And they map badly to legacy consumers, who've grown comfortable to having a collection of special knobs and dials perfectly shaped for their exact needs.
It does suck a bit, I've also sent Layer 7 into production which is just as bad as Axway. Typical Vendorware.
The AWS Gateway is pretty enticing. Solves lots of the API Gateway problem space very quickly and super cheap. We could run our production instance for about $2 a month I reckon, vs a 6 figure sum for the vendor tech.
[1]https://www.forrester.com/Sizing+The+Market+For+API+Manageme...
At a larger size, it may be more expensive than a roll your own, but for an independent idea that you just want to build something as a software/service and if successful be able to scale and handle extra load, it isn't a bad idea.
This is really the missing piece to Lambda in my mind... though being able to act as a bridge for legacy SOAP/WS-* services is pretty nice too. I've written a lot of pretty small node service that act as a bridge to SOAP based services the past few years... though most of those have been for internal use, and not sure how well that translates here.
Also API market is intended to grow to $660 million in US by 2020 and over a billion worldwide (http://blogs.forrester.com/michael_yamnitsky/15-06-07-the_ap...). So it's definetely not small.
It means you do not need to think about x instances that serve your API anymore. You just upload your Lambda function, wire some API path to it and pay per request. For smaller APIs this will be probably be negligible. Could be a gamechanger!
Rather than running an API server 24/7, you can write your API as a set of functions that cost you money only when they're actually invoked.
If you have a large cloud platform, an API gateway is priceless.
Especially if you have single sign on and therefore can use auth tokens for everything.
And because everything for them is already built on top of AWS.
In the API Gateway I work with allows you to do authentication within the gateway and then delegate responses to the back end API (which can still have its own security, if you really want it, but usually is just hidden on an internal network). It works pretty much the same for other things like rate limiting. It also gives you monitoring for each API, again cutting down on the things you have to add to every single API by encapsulating the function in the gateway.
Also, you can separate your internal API and your external APIs. Maybe you have to always support certain operations to the outside world, but internally you'd really like to change something. By having them separate, you can create a policy within the gateway to change how the internal calls are done without changing the interface as far as the outside world is concerned.
You can also do various types of conversion (e.g. REST->SOAP) or even more exotic things so that outside devs don't have to care just how weird your damned mainframe is or other aspects of your internal architecture that they shouldn't know about.
The target market is, effectively, anyone who wants to expose internal APIs to the outside world.
Source: I work on an API Gateway and this is how our product works.
November 3, 2017, SEATTLE
At the AWS Re:Invent in Las Vegas today, Amazon Web Services today announced the deprecation of Elastic Compute Cloud as it shifts toward lighter-weight, more horizontally scalable services. Amazon announced that it was giving customers the opportunity to migrate toward what it claims are lower cost "containers" and "Lambda processes".
"We believe that the cloud has shifted and customers are demanding more flexibility," tweeted Jeff Barr, AWS Spokesperson. "Customers don't want to deal with the complexities of security and scaling on-instance environments, and are willing to sacrifice controls and cost management in order to take advantage of the great scale we offer in the largest public cloud."
Barr went on to add that since their acqui-hire of Heroku last year, AWS has decided that the future of the cloud was in Platform as a Service (PaaS) and is now turning its focus to user-centric SSH key and user management services like https://Userify.com.
Amazon (AMZN) stock was up $0.02 on the latest announcements.
I was looking for something like this. Lambda functions are amazing but restricted because they weren't easily consumable externally. This is they key.
To put the minimum cache in front of your API costs more than running an EC2.micro
For my projected use where my volume are going to be so low that I will fall under the Free lamda tier and the very first API tier I don't need to worry about caching but for those that do the price will start to rack up.
I'm not sure about the costs involved with the caching options... just the same, I think this option is pretty cool.
http://i.imgur.com/wSEKeVb.png
I originally built it for the Swagger Spec 15 months ago, as the first visual Swagger Editor. Let me know if you guys are interested in using something like this.
Notice it has the code side-by-side. Also, it scrolls to and highlights the section of the spec you're editing. Notice the dropdowns are aware of custom models (e.g. "User", "Order") in the documents and suggest them to make it easy to use.
We used SwaggerUI for rendering in the beginning but that was replaced with it's own renderer. I blogged about it here: http://azimi.me/2015/04/23/swagger-editor-talk.html
Interesting! Re: SwaggerUI, it already existed as CoffeeScript and Backbone.js.
I built "Swagger Editor" for Tony, the creator of Swagger, as a paid OSS project; the screenshot shows the Swagger Editor back in Apr 2014 before yours existed.
I notice that a month later, you created "Swagger Editor" using the same technologies I chose (Yeoman, AngularJS, Ace Editor, etc) and took over the name.
I imagine the people who shared the private repository, including your employer Apogee, saw how fast I made mine and wanted to do their own from scratch, but I don't know.
I just took a look at your slides, looks like you've worked on yours for a year since, and use AST to understand where errors are, nice.
Of course, in a couple years, assuming success, the AWS lockin will suck. But given the odds of success I think I'd take the chance.
Is Tyk HIPAA compliant? I'd definitely like to use something like Tyk, but I manage an API that transmits health data, so lots of tools have turned out to be off-limits because of HIPAA issues.
However, we'd probably need to do an audit. Worth a check though.
Otherwise let AWS grow the market, and look for opportunities to serve people who don't want to pay the AWS premium and/or to plug feature holes.
My biggest complaint about MS/Azure is they can't seem to get single signon/off working right... Login to one account for personal email, another for work email, and another still for my personal Azure account... Sometimes gets stuck in a loop, just doesn't work, whatever... I often keep another browser, that I don't mind wiping all cookies on just to get the damned thing to work. Let alone the other day where my payment didn't go through for some reason, and my azure account was locked, as was my live account, that I had to go through a convoluted recovery process that was different because of 2fa, only then to have my email (application password) revoked... grrr.
Despite account issues, I've really liked actually working with Azure.. though I think their node tooling could use some TLC, and better documentation... wound up writing my own wrapper (azure-storage-simple) to have a cleaner interface... also wrote mssql-ng as a friendly abstraction on top of mssql.
We've been considering building something like this ourselves or looking for a good existing solution, but hadn't found anything yet. I'm definitely checking this out.
Flexibility however is always something you run into with platforms. And while this is a bit different then what folks typically think of as a platform (Django, Rails, Play, Spring) it looks like it would suffer the same problems. As soon as you need to do something weird, you're stuck fighting the platform or porting out instead of making your project better. This is why I prefer platforms that are more a collection of libraries with a preferred way of doing then as opposed to rigid box box style things.
We are accepting pull-requests from the community for new Plugins (http://getkong.org/plugins), and I can see Kong running on top of the AWS Gateway -> Lambda integration to provide functionality that is not necessarily bound to the AWS realm.
We're hacking on something really similar to this at https://stackhut.com, where we are building a platform for Microservices which are powered by Docker, can be run wherever through HTTP/JsonRPC, and are really simple to build/deploy. Think "Microservices as a service"... ;)
To give you an example, here is a task which converts PDFs to images: http://stackhut.com/#/services/pdf-tools, and here is the code powering it https://github.com/StackHut/pdf-tools which we `stackhut deploy`d.
We're about to open up the platform and would love to hear what, if you had a magic wand, you'd wish upon the product.
Shameless plug: after working on several API projects, I have been researching ways to not have to "code" over and over again what goes into creating endpoints, it became so repetitive. Lately, I turned to RAML (Yaml for REST) and, with 4 other developers, we created an opensource project called Ramses. It creates a fully functional API from a RAML file. It is a bit opinionated but having to "just" edit a Yaml file when building a new API simplified my life. As a bonus, I also get a documentation and a javascript client generated from the same file.
EDIT: forgot the url https://github.com/brandicted/ramses and url of a quick start tutorial: https://realpython.com/blog/python/create-a-rest-api-in-minu...
http://i.imgur.com/wSEKeVb.png
It would be nice to have one place to edit routes with a good UI, better than what Amazon released today.
No, we use Vagrant so that we can run our docker cluster either locally or on Amazon. We have stubbed alternatives for all AWS services, including SNS and SQS, allowing us to run the entire backend locally even without an internet connection.
> Have you been bitten by problems that you can't resolve because you don't own the product?
I'd say its kind of like coding in Ruby on Rails. If you are bit by a problem you can't resolve there is a high chance you are doing something wrong, or at least not the "one true way".
Sometimes we have issues when exploring the edges of what is possible on the AWS ecosystem (we've been using the fresh-out-of-beta ECS, and running into a lot of limits there), but generally the basic stuff like S3, SNS, SQS, Elasticache, etc just works, and doesn't require any attention. It's just a working, hands off gear in your system.
> Do you pretty much just love it?
Sure. It's a lot better than racking physical hardware, and the deep integration between things like autoscaling groups, EC2, ELB, etc makes it easy to automate all the things. In the end the more our service is a machine that can run itself and repair itself (replacing its own instances as needed) the more I love it.
Largely we've been very pleased with AWS, but the black box nature of a number of products (particularly Elasticache and RDS), has caused us some minor grief. Also, the higher frequency of single instance failures (which our stack can handle pretty gracefully) is somewhat annoying.
EDIT: We were also able to fairly significantly lower our bill with reserved instances while also significantly increasing our ability to handle peak capacity with AWS.
Basically, we just open a support ticket and say "what happened", and they just say "oh, the machine failed and was rebooted"
[1] Have a database of a few gigabytes of sizes, start an ``ALTER TABLE`` and wait until your pre-allocated disk space is filled up. The query dies and you just fucked yourself. Can happen unexpectedly: We tried to remove a non-existing index on a table and MySQL decided to FIRST copy the entire table and THEN report that there is no such index.
We weren't particularly locked in, either. We always had the option to run our own Postgres cluster (it just didn't make sense to spend the manpower on it for us). We could have hacked together our own CDN, but that wasn't our core business focus.
For small companies with low manpower, build on the services and get things done fast and as well as possible. It may cost more upfront than doing it on your own, but you are probably going to come out ahead by minimizing your maintenance/security/administration surface area.
Contrast this with using AWS DynamoDB, which would likely be a major overhaul if you needed to switch to something that could be used outside of AWS.
What tools are there to allow me to keep my code/API layouts in source control when uploading to this?
I'm sure they exist somewhere, so mostly curious about pointers. (A sample node project using this would probably go a long way)
That being said, having this as an option in AWS is pretty cool and potentially time-saving. I'll probably give it a shot soon.
1. What are the differences between this + AWS lambda and parse? Is there additional functionality or freedom with this route? Is it cheaper?
2. What kind of savings could one expect hosting an API with this vs a heroku standard dyno?
I doen't have experience with their product, but on surface they look similar.
Well, it seems that authentication for the client is mandatory. This makes it unsuitable for rendering markup and serving it directly to clients.
Can anyone confirm this can only serve JSON content? I suspect were anonymous requests allowed, I'd see my markup rendered as a JSON string.
Moreover I feel Lambda can do pretty good stuff. I am sure it will integrate with other AWS services pretty soon and once there is connectivity to an RDS instance, then it solves the use case for half the developer population out there.
Speaking somewhat from experience (webmethods, caml, spring-integration and various other enterprise integration tools) they always want you to use "their" DSL which is often not even stored on the developers filesystem (ie webmethods... you submit the code to the "broker" or "rules engine" or "router"... lots of words for thing that does the work). Which leads to very awkward development.
Consequently I wonder if they will have git integration because writing code even snippets in a web form no matter how nice gets old fast.
Edit: The submission title has been changed since this comment was written.
Actually, its an initialism (an abbreviation from first letters where each letter is pronounced as a letter) rather than acronym (an abbreviation from first letters pronounced as if it were a word.) Were it an acronym, many style guides (particularly British ones, IIRC) would support presenting it as "Api" rather than "API".
[1] https://github.com/mashape/kong [2] http://getkong.org/plugins/
http://ratemyapp.com/video/VIqZFaU1PhQ/Product-Preview-Amazo...
Companies like Apigee/Mashape/3scale/Mulesoft have been doing cloud API management in various forms since 2008. Even Microsoft Azure has an API management offering since two years.
Nowadays all those API gateway features are commodities and doesn't make sense to pay for it anymore. Indeed Open Source projects such as KONG [1] are getting tremendous tractions. Same things happened in search with all cloud solutions and then ElasticSearch came out and was game over.
There's value in integration and a lot of people want that.
So, the OP has an undefined three letter acronym.
Suspicions confirmed: The OP is an example of poor technical writing.
Why do I care? I could be interested in Amazon Web Services (AWS) for my startup. But so far by a very wide margin what has been the worst problem in my startup? And the candidates are:
(1) Getting a clear statement of the business idea.
(2) Inventing the crucial, defensible, core technology.
(3) Learning the necessary programming languages.
(4) Installing software.
(5) System backup and restore.
(6) Making sense out of documentation about computer software.
May I have the envelope please (drum roll)? And the winner is,
(6) Making sense out of documentation about computer software.
And the judges have decided that uniquely in the history of this competition, this selection deserves the Grand Prize, never before given and to be retired on this first award, for the widest margin of victory ever.
No joke, guys: The poorly written documentation, stupid words for really simple ideas, has cost me literally years of my effort. No joke. Years. No exaggeration. Did I mention years?
At this point, "I'm reticent. Yes, I'm reticent." Maybe Amazon has the greatest stuff since the discovery and explanation of the 3 degree K background radiation, supersonic flight, atomic power, the microbe theory of disease, electric power, mechanized agriculture, and sex, but if Amazon can't do a good job, and now I insist on a very good job, documenting their work, which is to be yet another layer of documentation between me and some microprocessors, then, no, no thanks, no way, not a chance, not even zip, zilch, zero.
What might it take me to cut through bad Amazon documentation of AWS, hours, days, weeks, months, years, then from time to time, more hours, days, or weeks, and then as AWS evolves, more such time? What would I need to keep my startup progress on track, 500 hours a day? More? All just to cut through badly written documentation for simple ideas, and worse documentation for complicated ideas?
First test: Any cases of undefined terms or acronyms?
Result: About three such cases, and out'a here. Gone. Done. Kaput. I don't know what AWS has, but I don't need it.
Sorry, AWS, to get me and my startup as a user/customer, you have to up your game by several notches. The first thing I will look at is the quality of the technical writing in your documentation. And, I have some benchmarks for comparison from J. von Neumann, P. Halmos, I. Herstein, W. Rudin, L. Breiman, J. Neveu, D. Knuth.
Amazon, for now, with me, from your example of writing here, you lose. Don't want it. Can't use it. Not even for free. I'm not going to invest my time and effort trying to cut through your poor technical writing. And, the next time I look at anything from AWS, the first undefined term and I'm out'a here again.
Yes, I'm hyper sensitive about bad technical writing -- couldn't be more sensitive if my fingers and arms were burned off. Whenever possible, I will be avoiding any chance of encountering bad technical writing, ever again. Period. Clear enough?
More generally, my view is that bad technical writing is the worst bottleneck for progress in computing. Come on, AWS, up your game.
I don't want to run a server farm and would like you to do that for me, but neither do I want to cut through more bad technical writing -- for that work, my project is already years over budget.
When you were toddler you started stringing those words together, and learning how to form extremely basic sentences.
And eventually you learned to form complex sentences with complex ideas.
The same thing applies to learning computing terms. AWS is now 9 years old, and has 9 years of development and features to catch up on if you are just starting. Yes, it will take some effort to learn everything, and if you don't see the benefit in doing so then you don't have to.
But if you want to be an "adult" engineer rather than a "toddler" engineer it is necessary to be willing to learn some things, even if it isn't easy.
The research libraries are awash with single texts that start with meager prerequisites and get to some quite advanced and challenging material. AWS can do so, also.
I've been in computing for a long time, but there's no hope for me to know all the jargon of all parts of computing. Mostly jargon is not conceptually difficult, and the solution to the challenge of jargon is simple -- just define it.
Parts of computing have long enjoyed having a closed priesthood that spoke in three letter acronym gibberish. IBM used to do this with PCP, MFT, MVT, MVS, JCL, DCB, IMS, DB2, CMS, SQL, and many more. And there were some four letter acronyms -- CICS, DASD, REXX.
The concepts were mostly simple; the gibberish was a secret language. Once I gave a grad seminar on computing and had a lot of guests from industry. IBM talked in their gibberish, but none of the other vendors did. The students caught on: IBM wanted to intimidate people and otherwise invite people into their priesthood where they, too, would understand the gibberish. IBM was the least popular of the vendors.
The linked article is basically a changelog for devs who have already been using the ecosystem for years, so no its not newbie friendly.
They would have been doing better for their business if they had made that point clear.
Again, my gripe is, better writing is needed. Why? The writing now too often results in absurdly high costs for absurdly poor reasons. The costs to me have me torqued.
We're just talking about bad writing.
Either that, that is, really poor business thinking, or, as I concluded, some poor technical writing. I don't believe the first.
Are you saying that you don't believe the Amazon technical blog is aimed primarily at existing AWS users?
If the that OP blog post was just for existing, old AWS customers, then find, good, okay, sure, of course, but make that point clear, up front.
Else, Jeff Bezos, I'm building a Web site; I've got the production quality, reasonably high capacity, scalable software written and running; HP has offered me servers initially for free; I plan, intend, and hope my Web site becomes a big thing; I should consider a cloud instead of my own server farm; AWS should be a candidate; I'm close enough now to going live that I should be looking into AWS; I read the OP to get started; I came away from that post and its poor technical writing torqued and wanting to set aside AWS even if I was offered it for free (for me to work through enough more AWS bad technical writing for my Web site would be much more costly than free, making a free service still too costly), that's a bad situation for Jeff Bezos, Amazon, AWS, and me.
There's a lot of absurdly bad technical writing in computing for absurdly poor reasons with absurdly high costs. I should have been torqued decades ago; I should be torqued now, and I am.
I just want better technical writing, in particular to save my time, effort, and money. For this instance, the blog just needed a common statement about "Who this information is intended for".
For AWS to put out information about their services with bad writing that torques off a highly serious and experienced software developer is bad business for both AWS and me.
I am just objecting to the costly bad technical writing. Simple. Should not be difficult, complicated, or controversial.
I want an article explaining how Amazon's API gateway works, not what all of Amazon's services are, what API gateways are, what REST is etc. There's already plenty of those out there. Not every article needs to explain every concept from scratch.
They even have a link to a page on what IAM is for those who don't know (admittedly it's not on the first mention, but that hardly makes the entire article badly written).
The OP failed to explain that a prerequisite to reading the post was being a long time AWS user. Then, the OP was bad technical writing. Done. QED.
Without such a warning about prerequisites, the undefined acronym was bad technical writing.
> your lack of knowledge of a particular set of technologies
That whole concept is big mistake common in computing. The "technologies" in question are, for at least a good first description, just dirt simple with meager prerequisites.
None of us in computing should try to carry the whole pile of simplistic trivia around between our ears. For a related lesson, after a while in academics, it becomes obvious that only fools try to carry the whole research library around between their ears -- the lesson is much stronger for the less deep, less good material in practical computing.
With good technical writing, nearly anything in practical computing can be explained plenty well enough to nearly any of us.
I don't have a relevant "lack" of anything in computing.
You failed to explain what OP meant, and didn't explain that your comment was aimed at people who knew this kind of terminology. Does that make your comment bad writing?
No one is suggesting that people should carry every bit of technology around in their heads. Google is a great source for finding things you don't know. The alternatives - explaining in every single blog post the complete set of terms that you need to understand to read it - would make for massive, unreadable posts and would be 90% useless for most of the audience it is aimed at.
> There was a hyperlink
Sorry, clearly that's just not good enough since the first use of the acronym did not have the link. The standard in technical writing is to take some steps to be adequately clear on terminology at or before the first, say, significant or material, use of that technology in the piece of writing.
> Google is a great source for finding things you don't know. The alternatives - explaining in every single blog post the complete set of terms that you need to understand to read it - would make for massive, unreadable posts and would be 90% useless for most of the audience it is aimed at.
Of course it would, but I've suggested no such thing. Instead, I was clear:
"With good technical writing, nearly anything in practical computing can be explained plenty well enough to nearly any of us."
Did I mention, my concern is good technical writing? I thought that somewhere in my posts here I mentioned that my concern was good technical writing. To be more clear, let me say, my concern is good technical writing. I want to be fully sure: Did I say that my concern was good technical writing?
For just what constitutes good technical writing, I won't try to give a course here and will leave that to other sources.
But, the good work in the fields of science, technology, engineering, and math (commonly called the STEM fields) has some really good examples of good technical writing. E.g., for science, see the freshman physics texts by Sears, etc. For technology, see D. Knuth, if only his The TeXBook. For engineering, see, say, D. Luenberger, Optimization by Vector Space Methods. For math, see, say, any of the more respected texts for freshman calculus going back at least 50 years. Also see the texts of W. Rudin.
The core problem I am addressing here is that the technical writing in practical computing is way too often really badly done with high costs for nearly everyone involved, really high costs.
Some of the comments here defending the original post are straining to defend the bad technical writing, making excuses for no good reason.
Let me say, likely the first good rule in good technical writing is to strain never but never have undefined terms, acronyms, and jargon; instead, on or before the first use of any such, have, for definitions, motivations, discussions, examples, explanations or at least links. E.g., write "Amazon Web Services (AWS)". Just do that -- always for the first use of the acronym AWS in anything at all about AWS. Just do it, always. Spend the extra three words. Be clear. Remove all doubt. Reassure the reader that in the piece of writing they just will not face undefined gibberish. Assure the reader that they don't need Google searches to get prerequisites for the piece. Be easier to read.
For acronyms, the example of API abbreviates both application programming interface and American Petroleum Institute is right on target -- for nearly any three letters, there are from several to many three words they could abbreviate.
And, if there is no reasonable way for the piece of writing to be for a broad audience, then up front say what the intended audience and prerequisites are.
This is dirt simple stuff. To accept these lessons it should be sufficient just to want to communicate instead of intimidate.
Are we communicating now?
And for AWS, IAM is a standard abbreviation. That's my point.
>Sorry, clearly that's just not good enough since the first use of the acronym did not have the link.
I've already acknowledged that, but one minor error - putting the hyperlink on the second use of a term that you could locate in 5 seconds in Google is hardly going to make the whole thing unintelligible is it?
>Did I say that my concern was good technical writing?
You did. And you've backed it up with pretty poor non-technical writing and a single complaint about the lack of hyperlink on the first occurrence of a single acronym that 99% of those reading an AWS technical blog would already know.
That point fails: HN has a much larger and more broad audience than AWS. Still, actually, HN should define OP -- I still don't have a good source to know what it means and have been only guessing. That AWS has a smaller audience than HN does not excuse omitting definitions.
Again you are assuming that readers of that OP blog are "99%" experienced AWS users, and that's not good. If the blog were only for such users, then I should say so.
That I could look around to unwind the acronym, later in the text, elsewhere on the page, on some other pages of the blog, elsewhere at AWS, at Google, doesn't excuse anything.
I mentioned some authors with some writing that is astoundingly technical, and there terms are defined as I described.
Computing is awash in bad technical writing; I should be torqued at it, and I am; one of the worst problems is poor handling of technical terminology, jargon, and acronyms; the blog post was an example: Either (A) define the acronyms on or before first usage or warn the audience that there are prerequisites.
Simple.
So it's HN's fault, not yours, that you didn't define a term that you chose to use?
And you're using a term that you don't know what it means?
> I should be torqued at it, and I am
What is "torqued" meant to mean in this context? I know what torque means, but it makes no sense when applied to this sentence.
The only question I had was, why regular Borel measures? Sure, if I went back and studied again where he used the hypotheses I'd see it.
But in Rudin's favor, e.g., for his Principles, it's all there, and crystal clear, very precise, and perfectly correct. Yes, have to draw own figures, at least between ears, maybe on paper.
Students might be told that one of the purposes of the early material in Rudin's Principles is to build a really solid foundation for discussing continuity and uniform continuity. So, for that, he wants compactness. He uses that work to show that, with continuity on a compact set and, thus, uniform continuity, the Riemann (Riemann-Stieltjes) integral exists. Then near the end of the book he shows that the uniform limit of continuous functions is continuous.
But, also he goes ahead and shows that a function has a Riemann integral if and only if it is continuous everywhere except on a set of Lebesgue measure 0, without really saying much about Lebesgue measure.
I don't have much from Apostol. I'm sure he could write a book that competes with Rudin's Principles and might be easier for ugrads to read.
It happens that two weeks or so I got out Rudin's Principles, the third edition, and looked up something and was struck at just how beautifully, elegantly, sparsely done the work actually is.
On elegance, Neveu is my favorite.
I can still remember picking up those 500 page computing books. Flipping through the phone book and putting it back on the shelf.
As to the overuse of acronyms; I think they are overused in this profession. It almost seems fashionable?
Jump to today, things have gotten better. I'm not sure the writing has gotten better, or I just have more presenters of the information(Internet)?
I don't know why you got down voted? The level of technical writing in this field is atrocious? I understand "these are tough concepts!". Yes, in many ways it's like learning a language! I get it. In most cases I'm glad someone took the time to write something down. Yes--I'm grateful.
I do have a problem with entities, with a lot of money/resources, whom publish terrible technical writting. It does seem like a big company, like Amazon, could have done a little better job conveying this product?