API design is a difficult topic. A lot of people have opinions about it and also nearly all of those people who have opinions are the wrong people to ask about it. Since you are reading an article about APIs it is fairly safe to assume that you already have at least some opinions about it already. You are perhaps here to read my screed against GraphQL or REST or similar topic, but I am going to disappoint you there.
In fact, if you're trying to figure out if you should build a GraphQL or REST API and you haven't answered one, simple question first then you are already well on the way to failing to build the correct API. You have put the cart before the horse and also when you realize the cart should be a plane, your horse will die. If you don't want to be a horse murderer, put aside the fact that I just said you are failing and please consider this question for a moment.
The first question of API design you should answer is this:
Should the API support building a feature complete, better looking version of the user interface?
Think about this for just a moment. If you are a developer of APIs you've perhaps heard of companies adding restrictive permissions or throttling to their APIs that make building a client impossible after someone build a much better app or site already. If you are not a developer then you may have heard ominous stories about company X "locking out third-party developers" or "shutting down ABC other service" or "accidentally murdering a horse in public" (metaphorically, of course). Regardless of which of those two camps you're in, hopefully we can all agree that you don't want to be responsible for making that happen to your company.
The failure here is changing the answer to that question at some point from Yes to No. If you answer "Yes" that you want to allow other people to do a better job of building your own application than you have done, that is fine. If you answer "No" that you want your users to stay on your site for their main experience, that is fine too. But if you answer "Yes" today and "No" after you're successful tomorrow, then you are in for a wild ride. It might even be so bad that business people or, you know, shareholders/VCs find out. So there can be a real cost to answering the question incorrectly.
For the business people out there, I have something to tell you. If you went to a developer and told them to "Make an API for our product" without any clear instructions or limitations then they have answered this question for you and their answer, almost certainly, was "Yes."
As I said, Yes can be a perfectly valid answer to this question but only if you are prepared for what it means. Imagine in your head for a moment that your wildest fantasy has come true (about your product... keep it clean, people). Your product is beautiful and stylish and easy to use. You see a user in front of it Getting Things Done™. They don't accidentally click the delete button when they want to save, they aren't missing the widget they want to click even though it is right there, and the whole thing is pretty and fast. Now imagine that the interface that person is using isn't made by your company. Sure, it is using your services underneath, but some random person on the internet you've never even heard of made that interface and it is better than the one you agonize over every day with your development team.
Are you happy? Will your boss be happy?
Again, "Yes" is a perfectly valid and perfectly lovely answer. If that's your answer, wonderful. You've got a product that does its job, an API that enables developers to work with your company, and people that are interested in putting in their own time to do just that. Take a long lunch and enjoy your day.
But a lot of business people would be absolutely terrified and upset by this situation. If the first reaction you had to that situation was "There's got to be some way to shut this down!" then your answer is "No" and you need to know that. Your developers need to know that. If your business is based on selling ads inside of your interface, for instance, you might have a really important reason for your users to be in your interface and not somewhere else.
If you find yourself in the unenviable situation of having to switch your answer from "Yes" to "No" it will mean telling people who are very interested in your product that they can't do that with it. It means you have to tell those really excellent, interested, probably paying users that their efforts are not wanted. If you're popular enough by this point, it might even make the news with phrases like "crackdown" and "locked out" and "unspeakable horse violence" and you really don't want that.
Excellent. If the answer to the question was "Yes" you can get on with Googling GraphQL vs REST. If the answer was "No" then you have a bunch of other questions to answer about what your API should do and why do you need one, etc. You can work through all of that and make something that is just right for you and for your users. If you can clearly answer these questions, then your legal team will write up the correct terms and conditions and your developers will build the right API and so on down the line. Your users might still want more access, but that is now a feature request and not a reporter asking you to comment about why you're so mean to your customers.
If you're a developer and someone just asked you to make an API, then consider for a moment whether they have answered that question. If you suspect they haven't, point them here or ask yourself just to be sure.
There is still plenty of work to do, but if you have thought about and answered this question then you haven't failed at the starting line and you will hopefully be spared the pain of realizing that you failed at API design only after you become popular enough for people to notice.
The door opened and time stopped.
From my vantage point only hints and suggestions were available to me. Yet I felt a thrill of emotion. I felt the brisk morning air from the open door energize me. My senses tingled in anticipation.
I tried to appear calm though inside I was singing. I tried to appear intelligent yet my mind was babbling nonsense.
The steam from my coffee cup rose languidly in the air in front of my face. I could not resist the pure joy of tasting the tiny notes of sugar amid the roiling chaos of dark chestnut. My lips sensed that it was nearly scalding and without hesitation I sipped. I let the sense of it all play throughout my mouth. The pleasure of this internal sensation, hidden from the world around me, kept my rapturous attention for the long moments as I waited.
My eyes had a clarity that my vision lacked. A spot. Removing my glasses transformed the world into sensation. The people of the coffee shop were no longer people, but feelings and experiences turned into color and splashed around the room. Here was the challenge of presenting to a crowd leaning around a pillar. Over there was kite-surfing for the first time in a couch by the wall. A warm blanket on a cold day stood behind the counter. Getting my first dog gesticulated wildly at the next table over. Approaching was the passion and confusion of my first kiss.
My formative experience took a seat across the table from me. My glasses, now clean, I returned to my face. Fitting them in position the world came into a focus unusual to me. I could see everything so clearly that I had a sense I was on the knife’s edge of being able to see the future. I spent a moment solidifying the experiences arranged throughout the room back into people.
Fixing my attention across the table, I managed a “Hello.”
“Hi!” she said, cheerily.
“I love you.” I said with the earnestness of just realizing the truth of it.
Laughing, she replied, “Of course, silly, we’ve been married for like 6 years. I love you too.”
Her smile was honey. In an instant I was lost in the pure sticky elation of it. My world for a taste. I remembered to smile back.
For anyone out there who is signing up for a gym for the first time, they will try to sell you Personal Training services. I received a free first personal training session. Instead of laying on my back while a hot guy pushed one of my legs back, it was more being intensely embarrassed about being exhausted after lifting a 5 pound weight for like 2 minutes.
After the whole ordeal was done, this scene unfolded. Probably you might wish to prepare yourself if you are ever in a similar situation.
Just 10 more. There you go. I got you. 3...2...1 perfect. That wasn't so bad, was it? Nah, I didn't think so. Let's just get a drink of water and head on back into the office.
Just take a seat right over there. How long do you think that was?
Yeah, you're right it was 10 minutes, but I bet it felt like an hour, right? hah, hehe
Cool, cool. I'll just go over all of these details and start filling in these forms. You said you weighed 235 pounds, right? Okay...
Here are your options. You could go for once a week for only $30 or twice a week for $50, it is that simple. Now there is an enrollment fee, which is usually $149 but I can go ahead and save you $50 on that right now, so that'll be just $99. Got it? Good.
Now we do this for 52 weeks, which is a full year. Can you think why we do it for 52 weeks?
Nah, not to lock in our profits for the year, it is because it takes time to build muscle. Getting to your goal of, let's see... "Moving a little bit every day." Well there's your first problem. You need a Goal. You need something to achieve that keeps you coming back. Sure you could just come in here and walk on a treadmill for a while and that would be better than not doing it, but you won't become truly healthy like that. You need to build lean muscle to get where you need to be. Anyway, we'll talk about that more in your first session.
Don't worry about the 52 weeks though, because here's what we do... If you, for whatever reason, miss one of the sessions it rolls over. So you don't lose it just because you missed one, you just make it up later with no worries. Isn't that awesome?
And if you want to cancel at any time they do this awesome thing where they'll buy back half of the total cost of the year that you haven't used yet. That way, you're not on the hook for the whole thing.
I see you hesitating, but let me just tell you, I've seen tons of people come through here and they don't last more than a few weeks because they don't have commitment. Sure, the anxiety you feel from just entering a gym is probably enough to counteract the entire pizza you ate for lunch but without goals and commitment, you'll just find some excuse not to come. We can work together to make sure you achieve those goals.
Look, you and I know that if a person isn't healthy then they are at risk for all sorts of problems. There is routine injury just from not being strong enough as you stand up off the couch, there is heart disease or even heart attack, as well as diabetes and other issues. And if you sign up for these classes, I'm sure we'll get you to the point where you can stay healthy 'at rest' which means you're burning calories and staying healthy without working hard at it.
So what do you say? Not yet? Look, there are 55 million people with gym memberships in the US and 60% of them don't use them at all. So if you sign up for these classes, we'll get you coming in here every week for sure and get you healthy. Because you don't want to wind up being a statistic.
Wait, hold up a second before you leave. Because if you walk out that door, you'll probably just wind up with a gym membership that you're already paying hundreds of dollars for just going to waste. If you want, we can start measuring your body right now and fill out your personal fitness tracker with your first week's information. That'll get you started down the path to being healthy. 9 out of 10 people don't come back after two weeks of signing up for a gym. I've never seen someone stick with it without commitment like this. So let's get you on the path so you won't become a statistic, because statistics DIE.
Oh! Hey! Come back! I can take another $50 off the enrollment fee!
Resident Evil Colon The Final Chapter is definitely, mostly a movie. There are maybe 10-20 people out there who are going to consider watching this movie but have not yet made up their minds. I don't even understand how that is possible, but I will get to you folks in a minute. For the other groups...
You wonderful, productive people are not missing anything at all. If you are in this group of people, you are probably an attractive and well-to-do person about town. You have better things to do than read this. Go buy a comically oversized scarf or take a rock-climbing course, whatever it is you kids do these days.
The only one, minor piece of information that might sway you to go see this movie is J Bear. Yes, THE J Bear is in it:
He says things with his J Bear voice. None of the dialog is particularly good except there was one line where he says something about "three bitches" which made the only other person in the theater I was in laugh out loud. But if you need more of the raspy love tones of Iain Glen whispering sweet, sensual nothings about zombies and driving a tank into your ear, then this movie has those things.
You people. You fucking people. You're my guys and girls. You're my people.
This is the sixth movie in a hexalology or hexililogy or whatever the six version of the word trilogy is. If you have seen at least 60% of the previous 5 movies then you know you're probably going to see this one. There is no point in denying it. Just go. It will be a nice time. Alice, aka Zombie Multipass, is in it. Claire Redfield is in it for some reason. The movie theater will be mostly empty so you can stretch out and put your jacket on the chair next to you instead of trying to find a comfortable way to sit on it without it touching the ground.
I guess I should also say that I saw this in 3D. I cannot recall any reason for this movie to have been in 3D at all. Let's say all that means is you have to wear Buddy Holly glasses for 100 minutes.
I know, the world can really grind you down. Life comes at you fast and all that. "They made six of those??!?" Yeah, they did. Here is the ONLY scenario in which a person who is not sure about seeing this movie should actually go see this movie. If this scenario doesn't describe you and you haven't already made up your mind, then skip it. The first Resident Evil movie is probably on Netflix or whatever, just go watch that.
But here we go with the scenario. Let's say you're in high school and you've picked video production instead of shop class for an elective class. Then, you make friends with the teacher and convince him/her to let you start your own public access TV show. And you've got an idea... <drum roll>... You're going to review movies. Awesome. Perfect. Now your teacher is a real cool dude/dudette and he/she knows a way to hook you up with free movie passes at the local ZillionPlex 5D UltraScreen Theatres because you're big time movie reviewers now. And you're beyond excited. You're ecstatic. You're elated. So you go to the movies and you see everything. You're watching movies after work. You're going to see a movie after you just saw a movie. Goddamn butter is coming out of your pores. You've seen every last movie the theater has a listing for including that weird one that is some kind of special event single showing thing that you didn't really understand. And the only one you haven't seen yet is "Resident Evil: The Final Exposition." There is literally nothing else and you've got a free movie pass on a lanyard around your neck. A lanyard. If this situation, in every single detail, describes you and who you are right now, then you should go see this movie.
Everyone else: skip it.
A new dawn shined brightly through my skylight. The sun crept across my face and slowly roused me from my dreams. I was having another one where Marcus and I were in the center of a protective circle declaring our love for one another. I can barely contain my excitement for the wedding even though it is still months away. I gingerly uncoiled the covers and crept out of the bed, trying not to wake Marcus who was snoozing away.
I busied myself with my morning routine. First some meditation, then my vitamins, then a few minutes drinking my morning juice while catching up on the news. I sat at the kitchen table and popped up ResistR to get updates on the progress of protests yesterday and any new issues that we'll have to deal with today. It looked like yesterday's airport protests went well. People seemed to have turned up at all of the international airports and a handful of local only airports in symbolic solidarity. A few pictures of children of various faiths holding protest signs and chatting together in the crowd have gone viral. A few reports of pepper spray being deployed and some pictures of little children in handcuffs for some idiotic goddamn reason, but no deaths or serious violence. All in all it was a good day of protests. We were getting our message out.
And now, the most dreaded part. Finding out what fresh hell the government decided was going to be today's issue to protest was always a roller coaster ride. Would it be a standard statehouse protest or would we have to change-up the location today? Would we need to make custom signs or would the normal ones do?
A jolt of annoyance shot through me as I remembered last Tuesday's ban on Muslims serving food to Christians. I had planned to go to a new kind of yoga class that morning where they would read out passages from a book of meditative ideas while we were practicing. The classes were always packed and I had to sign up a month in advance. But, of course, we didn't have a sign ready for the right to serve food to Christians. Who even thinks of that kind of nonsense? The government was getting so many crazy, new ideas lately we had run out of poster board too. So instead of going to my yoga class that I had been looking forward to all month, I had to go stop by the PRO-test store to pick up some more poster board and make new signs in time for the march. Sigh.
I tapped the 'Unite Today' button to see what the plan was. Thankfully the government spent all day yesterday trying to explain why the 8 year old in handcuffs was a threat to national security and they didn't get around to unleashing whatever hateful crackdown on human decency they had planned, so it was just going to be a normal statehouse protest with the usual signs. Maybe today we'll go with something more fun and less issue specific. I always liked "OH HELL NO" for a fun one. Sometimes you have to bring out "I AM QUITE UPSET" or "STOP KILLING PEOPLE YOU FUCKING TWATS" but maybe not today. Today, I think I'll wear my green and black yoga pants and that goes well with the colors of OH HELL NO, so that seems like a good choice.
By the time I was done with my morning routine, Marcus was finally up. I got a groggy hug and an offhand "How'd you sleep?" before I got out the door. I stopped by my local coffee shop and got my #Resistance discount on a Café Mocha. The line was shorter than usual. I guess some folks decided to take the day off since there wasn't anything new to protest. Maybe I'll take it easy today too. I took out my phone with the raised fist in black and red case that went perfectly with this new beret I got and hit the button for a LibreRider to come pick me up. Usually it was hard to find any drivers on the non-evil taxi app, but sometimes when it was slow like this you could snag one. And I was in luck too, only 4 minutes away.
The driver took me all the way down to the statehouse. It looked like a few early birds (or overnighters, it was hard to tell) were already out marching and chanting with the usual signs, but there would still be plenty of time before it picked up for real. I felt like I had enough time to slip in to MOVEment across the street for a wake-up yoga class. It was just a beginner class, but Mary was teaching it and she always knows how to get the right energy for protesting flowing through my body.
After my class, I was raring to go. The crowd outside the statehouse had reached a respectable size. I saw Marcus walking around with a "NO WAR FOR OIL" sign and snuck up behind him. I grabbed his butt and yelled "Gotcha!" to surprise him. He was excited this morning too, so I gave him a big kiss and we both fell in line together. This morning was a hearty round of "Show me what democracy looks like! / This is what democracy looks like!" I held Marcus' hand tightly as we marched and yelled. I still couldn't believe I found a man I loved enough to marry, but I guess I'm just lucky. Today was going to be a good day.
As our country crumbles down around our ears an interesting aspect of people's reaction is that it is frequently suggested that this is a white people problem or white people are unduly upset about it.
Even just after election night there was an SNL sketch about it.
As a white person, this whole Trump nonsense gives me the screaming heebee jeebees. I'd just as soon let the politics happen according to more informed people's opinions, IDGAF. My white privilege assures me that I can ignore things which I find in any way inconvenient. I guess you could say I'm a Democrat since I typically would vote that way, but mostly I just prefer when things make sense. I believe that it is part of the government's role to try to improve the quality of life within the country and make sure the economy doesn't collapse in addition to all of the foreign policy stuff. On some long forgotten level I suppose that also makes me a Democrat, but I don't really know if the parties break down like that anymore.
Also as a white person, I benefit from racism. As a man, I benefit from sexism. It is great to have benefits. If you get the chance to be a run-of-the-mill straight, white man I suggest you try it for a while. What is not so great that my benefits come at the expense of others. That cost is not worth the benefits that I get, at least not for me. Now I may not believe that I am in some way personally responsible for racism or sexism to any significant degree, but I understand that I have benefited from those things. My ignorance of complicity in them probably means that I am guilty of supporting them through my direct action. I have generally been open to the people in my life saying "Hey, asshole, thing X you're doing is bad and wrong!" and I will try to change my behavior. None of this matters except to give you the context of who I am.
Donald Trump's election isn't just dangerous because we will turn a blind eye to some racist policies or some traditional American oppression. We certainly will do that, but that is not the new hotness of horror causing all of the white angst. The danger is that he isn't just racist, but he wants to build a giant, 2,000 mile long monument to racism along the Mexican border. The danger is that he isn't just a creepy old guy when it comes to women it is that he is a criminal, a sexual predator. All he seems to value in others is loyalty, but not normal loyalty. He wants some kind of creepy, sycophantic loyalty where he will humiliate you in public just to force you to demonstrate that you are subservient to him in all ways, in all things. He will do these things at the expense of reason and if necessary at the cost of the very thing any reasonable person would want or what might be good for the country.
Now, as a white, male, middle class person I generally do not live with any kind of fear about my situation. The scariest thing I think about on any kind of routine basis is that a bunch of evil ninjas will jump out of the bushes and I'll have to Bruce Willis them all to death. Yes, I am afraid of the police when I see them, but I am not afraid that they could kill me because I'm wearing a hoodie and get away with it. I have a belief (perhaps wrongly, but still) that if a police officer killed me they would be held responsible for that act. Now, I also understand that many black people do not feel that same way about the police. That many black people feel like the police can take their lives with impunity. The fact that those feelings are justified is horrible and needs to be corrected, but the only point I'm trying to make is that at least some black people walk around with the feeling in their hearts that their very life can be taken from them without consequences for the person responsible for it. That feeling is not a feeling that I have on any routine basis about my own safety.
That feeling with respect to being killed by a police officer is just an example. I believe that this same justifiable fear of this type of danger spreads across many other areas of people's lives. I mention black people specifically, but I believe that in America straight, white, middle-to-upper class men are the only group who has the privilege to not have to feel that way about any aspect of their lives. What that means is that I am free in a way that blinds me to the fact that others do not feel this way. I am in no danger. I think everyone should feel like this and, frankly, I often feel like they do even though intellectually I know they do not. The lack of whatever this fear is, is the reason that communicating those types of problems to white people doesn't work very well.
Now the reason Donald Trump is so terrifying to white people is because he gives us that same kind of fear. Because Donald Trump is president, I am no longer free. I am in danger. Having Donald Trump as president risks not just increasing the institutionalized racism, misogyny, xenophobia, homophobia but it adds to that list everyone who is not a Donald Trump loyalist. I am not usually in one of the groups listed in any list of -isms and -phobias. But now, because of Trump's election I have a feeling that if my life is inconvenient to Donald Trump he will take it from me without any consequences for him. Of course he won't do this personally, but things in this country can change in such a way that it is possible or even probable.
President Bush sent Americans of all colors and genders off to war. He knew that some of us would die. He judged that price acceptable for whatever ends he desired. You may, and I do, judge him harshly for that. He paid for revenge with the lives of Americans and the lives of innocent civilians. History will not be kind to him. Yet I do not believe that he did this capriciously and completely without regard for the cost. He may have done it without proper respect for the cost. He may have been misled or confused or just some kind of moron, but I don't believe he was flippantly disregarding American lives.
President Donald Trump will take your life for no greater reason than because he can. You will die because "When you're president they let you do it." Everyone who is not personally, secretly manipulating Donald Trump or personally, publicly submissive to him is in danger. Because he is in charge of the most powerful military in the world, the entire world is now in danger. Consider his statement about Iraq's oil, "...we should have kept the oil. But, okay, maybe we’ll have another chance." The moment Donald Trump took the helm of the most powerful military in the world, everything in the world became his for the taking. And he will take. He will fleece the money out of the government for himself. He will take bribes, he will set up institutionalized payments into his own pockets. He will use the military to take the things he wants that people aren't giving him, including respect.
Everything Donald Trump wants, Donald Trump will try to take. And if your life is in his way, then you are in danger. That is a threat that straight, white, middle-class men are now subject to in a way that we were not under Obama or indeed at any other point in my lifetime. Of course, all Americans and, indeed, pretty much all people in the world are under the same threat, but the fact that it is new for people like me is what makes it so palpable to us. A lot of white people are maybe complaining that Donald Trump's election means the country is racist in a way that they did not previously acknowledge, but I personally believe that the truth is that we now know that whatever hatred is behind that thing we call 'racism' also applies to us. That is what people are so upset about.
I think the term 'racism' is too specific to describe what is really happening. Yes, racism won in the election, but so did misogyny, so did homophobia, so did tons of other terrible things. This time, hatred and willful stupidity won. If you believe that hatred won't apply to you because you're an American citizen, then you are wrong. If you believe that hatred won't apply to you because you're white, then you are wrong. If you believe that hatred won't apply to you because you're a Republican, then you are wrong. The only people who are completely safe it seems are members of Donald Trump's family.
I am not trying to say that white people are special in being threatened by Trump like this. I am only trying to point out why the perception exists that white people are unusually upset about this. Feeling existentially threatened in this fashion is new to us, so forgive us if it is shocking. If "Trump" wasn't becoming synonymous with a million other terrible things, I'd suggest we call this a "Trump Feeling" and it could be used to communicate with white people, a la:
Black person: "Black Lives Matter." White person: "But surely All Lives Matter, right? Why would we talk about black lives specifically?" Black person: "Because this police situation gives me a Trump Feeling." White person: "Gotcha. What do we do about it?"
Woman A: "Having a bunch of people randomly compliment me when I walk down the street is scary." Man B: "But why, we're just trying to be nice." Woman A: "Because it gives me a Trump Feeling." Man B: "Oh god, I'm so sorry. I never realized."
Of course, we're in this thing together. We were always in it together. I don't think we can just roll this back to before Trump happened. People will die. Harm will come to Muslims and LGBT folks and Latinx people and white people as a result of the idiotic hatred of this administration. This is going to do lasting damage to everyone in a rainbow of different, shitty ways. The good news is that they are not very good at their jobs, they are just unusually evil and vile beyond what we have protections for. If we come through this with the country still in tact, we'll be able to protect against it happening again. At the very least, we'll all be together to try to withstand it and help one another through. Maybe your children or your children's children will get a chance to be as ignorant of the Trump Feeling as white people were 4 months ago.
Dear Diary -
10 minutes ago I read one of the most inane sentences I've ever come across. 9 minutes and 55 seconds ago, my eyes rolled back so far into my head I couldn't see anything anymore. I fell out of my desk chair and started writhing on the ground. I think I started speaking in tongues. For a while, yapping like a dog seemed to bring some relief to my situation. The more aggressively I yapped the more the chaos and uncertainty of my tortured existence seemed to recede. Yet, the yapping also took me farther away from my humanity. With each yap, I could feel myself becoming... other. After interminable minutes, my throat went sore and dry and I was left gasping for air on the ground. I held onto the carpet as if it were my only connection to objective reality. Finally I crawled into the bathroom and managed to choke down some water directly from the sink. Long minutes passed before full consciousness returned to me. Slowly I regained my humanity and began to piece together my brush with the infinite, unknowable recesses of the human soul and the darkness that exists in all of us. I vowed never again to read the "What folks are saying about us" section of a service directed at marketing people.