Web APIs for new developers

Dear new developer,

Chances are high that you’ll be working with other code as a developer.

I remember when I was first starting out and saw the acronym API everywhere. I had no idea what it stood for. In case you are in the same boat, it means Appliciation Programming Interface. What that means is it is a defined way for your code to call into another piece of code.

One of the most common ways to do so in an interconnected time is via a web API. A web API (as I define it) provides significant functionality for your application, across the internet, over HTTP. You may or may not control the API, and you may or may not use an SDK to access the API. (There are, of course, many other ways to integrate other functionality into your application, depending on what you’re doing.)

This article does a good job of discussing some of what you should be aware of when you are accessing web APIs. In particular:

First, a clarification: the term API is used to refer to lots of different things, and its emphasis has shifted a great deal over the years. If you’ve learned anything about Object Oriented development, you may be familiar with APIs as code components that have well-defined interfaces, allowing “customer” code to access the features and functionalities within a system. These APIs usually involve objects and methods / functions. This is not the type of API we’re going to talk about in this article. 😅

In this article, we’re dealing with the kind of API you use to manage access to data and services over the web. If you’ve come across the terms HTTP API or REST API, that’s what we’re talking about. With this type of API, client apps make requests to endpoints to carry out operations on data. An example would be a database for a shop that has a web app and a mobile app – with an API managing access to the data from both apps.

The article goes on to discuss different concerns you should have as a developer interacting with web APIs.

The power of web APIs is that you can gain access to a quite complicated system via a simple API call. Examples of this include:

  • Looking up stores or restaurants that are close to you (Google Maps)
  • Making a charge against a credit card (Stripe)
  • Sending a text message (Twilio)

These all used to be tremendously complicated tasks, sometimes taking weeks to months to set up. Now you can access them and put together an application that does all three in hours. We stand on the shoulders of giants, indeed.

You don’t just benefit from the API integration one time. The API provider has an incentive (especially you are paying them in data or money) to improve their service. And often you can get the benefits of that improvement without lifting a finger.

If you have a large task that you want to do as part of an application, it’s worth googling around a bit to see if someone has already encapsulated it in an API.

Sincerely,

Dan

Talk first, code later

Dear new developer,

The more experienced I get, the more I realize that the hard part of software development (for the kinds of software development I do, primarily business web applications) is not the coding. It’s the communication.

You need to communicate, often among shifting parties over weeks, months or years:

  • why you are building something (to motivate people)
  • what you’re trying to build (to make sure builders have the same vision)
  • how you’re building it (to make sure that builders’ various components work together well and are cohesive)
  • when it will be done (so that all the follow on pieces of work–sales, marketing, etc can be scheduled)

Whew, that’s a lot of communication. But it’s important.

This piece, “Talk First, Code Later”, talks about the same problem from a different viewpoint. From the post:

After we all got on the same page, we made a plan, the other team abandoned their original change, and we agreed on the way forward. In one case, we shipped the new feature that unblocked the other team. In the other case, we coached the other team on how to implement the change in a way that we could accept the pull request.

It also has some handy tips on how to maximize communication when you are making a change to a system with which you have minimal familiarity.

The whole post is worth a read.

Sincerely,

Dan

Skill stacking

Dear new developer,

I found this post, “How to Become the Best in the World at Something”, enlightening. The author is arguing that if you pick one area to be the best in, you’re going to have to be very very good at it. For example, if I wanted to be the best in the world at building websites with Rails, I’d have to work very very hard at it.

If you, on the other hand, pick a few things to be excellent at, you will have an easier time being the best in the world who can do all those things well. For example, if I were to be the world at building websites with Rails for CSA farms in the USA with ecommerce and email functionality, I’d have to understand and be good at:

  • building websites with Rails
  • knowing the needs of CSA farms
  • understanding ecommerce
  • knowing email strategies

I’d need to know a lot about all of these, but I wouldn’t need to be world class in all of them to be world class in the overlap between them. The post has some nice graphs illustrating this.

Here’s a great quote from the post:

Let’s run some numbers on this. If your city has a million people, for example, and you belong to the top 10% of six skills, that’s 1,000,000 x 10% x 10% x 10% x 10% x 10% x 10% = 1. You’re the number one person in your city with those six skills. Bump that number up to 10 skills? Boom, you’re the best in the world at that combination of 10 skills.

This is another way of saying what a lot of business advice says: nicheing down is an effective business strategy. By nicheing down, you are decreasing the number of people that you are competing with and also making it easier to market yourself to people who need you. It’s a lot easier to focus on CSA farms who need ecommerce websites with email and to gain excellence in understanding their problems and potential solutions than it is to gain excellence in all things Rails. (I wrote about this a bit in deep vs wide experience.)

The whole post is worth a read.

Sincerely,

Dan

How to succeed at a larger company

Dear new developer,

This Ask HN is worth a read, as there are some good tips on how to succeed in a larger company.

I’ve been here for about a month now and still feel like I’m mostly just in free falling trying to figure out 95% of what anyone talks about or how to do things. It seems like everything works fundamentally differently than it does for a smaller scale company.

Some of the advice:

Take always a notebook and a pen with you. Whenever there is a word, or process, you have never heard of or are not sure what it consists of, write it down.

Now every few days schedule a meeting with a member of you team, reviews the list, and request explanation/clarification.

Take additional notes for future reference. That’s it, in a few weeks you’ll feel at ease with what is happening around you.

This is a gradual process, you’ll keep learning in the months, years to come.

This is a good tip for any new job. Take notes, make sure you try to get a bit better every day. Even at a super small company, while you may feel pressure to deliver right away, reasonable people will expect some spin up time. When I was at a small consulting company, I was expected to start really understanding things in about a month, not in the first week. Give yourself some time.

But do take notes and find out when you should ask questions. Some teams will want you to ask questions as they arise, others might want it more structured. If you can, document for the future (wiki, github READMEs, etc) so ask about doing that.

(Side note, in my experience, if you succeed in delivering anything in the first week that is going to be a feather in your cap. I remember delivering working code in the first day or two of a contract at a large company where I was hired as a senior developer and having the product owner be suprised.)

Another commenter mentions that there is more communication overhead in larger teams.

As you are noticing, there is a lot of communications overhead for large teams.

I have spent most of my time at smaller companies, but have worked for a few big ones (> 50k employees). It’s a different world, in my mind, one where ability to communicate becomes even more important. This is true for everyone, both the individual contributors (ICs) and management.

Sincerely,

Dan

On surviving your first year as a developer

Dear new developer,

This post covers some great tips on getting through your first year. It starts off ominously:

The first year as a programmer is one of the most frustrating things a homo sapien can experience. You’re thrust from the world of ambiguous human communication into the icy waters of cold, hard correctness. There is no compromise with the machine. It does exactly what you tell it to, no more, no less.

But then moves to some good advice, about advice:

There are very few absolutes when it comes to practical programming. A Technical opinions of developers are based on their experiences, the books they’ve read and the technologies they happened to work with. No one does a thorough survey of the technology landscape before declaring their support for a given tool, application or methodology.

This is so true. Everyone’s opinion is path dependent. I was a MySQL user for years and thought it was the best open source database, until a chance comment from someone I was chatting with at a meetup (see, you should attend a meetup) mentioned that PostgreSQL has transactional DDL. That is, you can alter a table as part of a transaction, and they roll it back. (Happy to report that MySQL has made progress on this, though I don’t believe they are at feature parity yet.) If I hadn’t run into that meetup participant, it is unlikely I would have learned that nuance.

Multiply that experience by the hundreds of decisions a developer makes every year based on their knowledge, their problem space and their work environment and you can see how different advice can be. And to be fair, how it can all be valid, based on context.

The post also covers ego-less coding, what to learn, and the joy of bug hunting. The whole post, “Survive your first year as a programmer”, is worth a read.

Sincerely,

Dan

How to learn things, fast

Dear new developer,

I enjoyed this post about how to learn. While the author toots his own horn a bit much for me, he makes some very valid points about how to learn. Most importantly, you want to learn using the best resource. What is best?

The best resource is a bit of a lie – it’s really just the one that’s best for you, given your prior experiences and the medium you enjoy. You’ll usually only know you found it in hindsight.

And, once you’ve gained an intermediate level understanding of what you are trying to learn, you should:

Stop. This is counter-intuitive, but unless you want to become a master at something (besides learning), you really just want to know everything at an intermediate level.

The whole post, “How to learn things at 1000x the speed”, is worth checking out.

Sincerely,

Dan

Benefits of blogging

Dear new developer,

I’ve written before about my belief in blogging as a way to sharpen your thoughts and give examples of your expertise. Here’s a post along the same lines. From the post:

People always try to find someone they can trust. You can go through a series of interviews and hope that they will figure out you are a great colleague, or you can write about your approaches and let a wider audience know that.
If you have a deep expertise in some technology, you can demonstrate it by writing deep and thoughtful blog posts.
If this technology is in demand, you will definitely get some opportunities coming your way!

And

Your views expressed publicly can be a good conversation starter.

This may come handy in any professional social context: interviews, meetups, conferences. It’s a different level on conversation when you get approached because someone likes your views.

The author then goes on to talk about specific, measurable ways that his blogging has helped his career.

The whole post, “Is blogging useful?”, is worth a read.

Sincerely,

Dan

Schleps

Dear new developer,

I remember reading this article a few years ago and being struck by the wisdom contained therein. Code and development is crucial to building many businesses, but as developers we often get wrapped up in the code to the exclusion of other things.

I have definitely discounted the value of other aspects of a business (marketing, sales, accounting) in the past. That is a mistake, as there are many many things that need to happen to deliver value to a customer.

Doing a schlep is a great way to inexpensively deliver value to customers. It doesn’t scale, but it is far quicker to change a manual process than to change code.

From the essay:

No, you can’t start a startup by just writing code. I remember going through this realization myself. There was a point in 1995 when I was still trying to convince myself I could start a company by just writing code. But I soon learned from experience that schleps are not merely inevitable, but pretty much what business consists of. A company is defined by the schleps it will undertake. And schleps should be dealt with the same way you’d deal with a cold swimming pool: just jump in. Which is not to say you should seek out unpleasant work per se, but that you should never shrink from it if it’s on the path to something great.

The whole post, titled Schlep Blindness, is worth a read.

Sincerely,

Dan

Things learned from a senior developer

Dear new developer,

This post by a Bloomberg developer catalogs everything they learned sitting next to a senior developer for a year. Lots of good stuff in there. Favorite excerpts:

How to handle an outage:

For when things go wrong, and they will, the golden rule is minimizing client impact.

My natural tendency when things went wrong were to fix the problems. Turns out, it’s not the most optimal solution.

Instead of fixing what went wrong, even if it’s a “one line change”, the first thing to do is rollback. Go back to the previous working state. This is the quickest way to get clients back on a working version.

Only then should I look at what went wrong and fix those bugs.

This is really good advice. When you are under pressure in a production outage, the tendency to try to figure out what is going on can be very powerful. However, figuring out the root cause of the issue is probably not as important as restoring functionality to your end users. Roll back. If you won’t be able to replicate the issue in your staging environment (due to load or some other reason) save off your logfiles and note the start and end times of the outage for further analysis (slack is good for that).

On code reviews:

Code reviews are amazing for learning. It’s an external feedback loop on how you’d write code vs how they write it. What’s the diff? Is one way better than the other? I asked myself this question with every code review I did: “Why did they do it this way?”. Whenever I couldn’t find a suitable answer, I’d go talk to them.

After the first month, I started catching mistakes in my teammates codes (just like they were doing for mine). This was insane. Peer reviews became a lot more fun for me – it was a game I looked forward to – a game to improve my code-sense.

My heuristic: Don’t approve code till I understand how it works.

Code review is definitely a skill worth practicing. You don’t want to nitpick and I’m a fan of automated linters/code style enforcers. That way you can have all the ‘where does the brace go’ arguments once, and then have the rules automatically enforced. Of course you can look for bad variable and function names, and that is valuable (and non automatable). But in my mind there are two aspects code review that are harder, but more important:

  • How does this fit into the overall system. Are there other components that should use this code or be used by this code? Is this structured correctly?
  • Do I understand this code and what it is trying to do. This means you need to understand the problem that the code is solving.

The whole thing is worth a read.

Sincerely,

Dan

How to get the attention of a busy person

Dear new developer,

This post talks about how to ask for mentoring, but the principles apply to getting in touch with any busy person. Busy people are by definition busy, and get a large number of emails and requests every day. (Here’s a VC talking about the difference between ignoring and not replying, and how they look the same to a sender.)

The key is that you as the requester need to put in some effort. From the post:

In other words, when you asks for a busy person’s time for “mentorship” or “advice” or whatever, show (a) you are serious and have gone as far as you can by yourself (b) have taken concrete steps to address whatever your needs are and (optionally. but especially with code related efforts)(c) how helping you could benefit them/their project.

This effort on your part shows that you are serious. It qualifies you. Especially if you persist. (Now, you can’t persist to the point of annoying the person. There’s a line between persistence and bugging someone. I always preface any email I send to someone asking a favor with ‘hey, feel free to tell me to buzz off’, and I mean it.)

And

I hate to sound all zen master-ey but in my experience, it is doing the work that teaches you what you need to do next.

That doesn’t mean you can’t learn from reading (otherwise why have documentation or even this blog!) but that you need to actually try things outlined in docs. Even just typing the commands of a tutorial (instead of copying and pasting) will help you understand what you are doing.

The whole post is worth a read.

Sincerely,

Dan