Teapot

I was looking through the list of HTTP status codes and saw a strange one.

Error 418 (I’m a teapot)!?

Google have a dedicated teapot page:

If you hover over the teapot, his eyes open and he smiles. If you click it, it then animates.

It sounds like the origin was an April Fools prank.

RFC 2324 was written by Larry Masinter, who describes it as a satire, saying “This has a serious purpose – it identifies many of the ways in which HTTP has been extended inappropriately.” The wording of the protocol made it clear that it was not entirely serious; for example, it notes that “there is a strong, dark, rich requirement for a protocol designed espressoly for the brewing of coffee”.

wikipedia

How (Not) To Split An API

I’m a software developer that only really has experience on desktop apps, and was recently put on a project to make an API. I had an interesting debate with the Tech Lead of the project about where we should put our code, and how we should view its responsibilities.

To make it more anonymous, I’ll change the functionality slightly but it’s the same idea.

An Orders API had been in development for a while, and my team needed to add functionality to send some data to a government API, so let’s say it was for ID verification. Even though our initial requirements are that only the OrdersAPI will use the VerifyAPI, you could argue that in future, maybe in future, other applications we have made, or third parties could call this VerifyAPI directly.

There’s a famous idea in software development; YAGNI; You Ain’t Gonna Need It. Which is the idea that you should program to requirements and not speculative “what if” scenarios.

The Tech Lead argued that we should put our code in a new repository because it was a separate API. I said that that adds loads of overhead because we will need to write code in OrdersAPI to call our code, then will need to add a reference to our VerifyAPI using a Nuget package. This will slow down development as you need to update 2 repositories, need some temporary reference as you develop, create multiple “Pull Requests”, then need to publish the Nuget package and update the references once more. I stated this was gonna be a huge inconvenience if the project ends up running over the year.

I also called YAGNI on that we will probably never use the API for anything other than OrdersAPI so it should just go in the same repository. In the event where I am wrong, it should be fairly easy to move it out as long as we just use separate projects to keep our code separate.

He insisted on doing things his way, but the thing is, even though we had a separate repository, it wasn’t a separate API. It was more like a code library. So several months later, he was asking managers if we can create a “mini project” to turn it into an API for clearer separation.

So it seems like we had 2 opposing viewpoints but ended up somewhere in between with all the disadvantages.

Another interesting debate I had seemed to illustrate his confused view of what our code is. He has always viewed our code as intending to be an API, but I was changing some error messages and he said my messages were misleading because our repository is not an API!

The confusion seemed to be him saying the “client” is the OrdersAPI, but I see the user of our software as the client, the OrdersAPI is the server call, and it doesn’t matter where it goes next

The message was something like. “Field ‘Date of Birth’ is missing”. He didn’t like the word “field”

Tech Lead
"I'd change the wording on these messages. We're no longer talking about "fields" since we've split the API request out."

Me
“does it matter where our code is? it's part of the same request as far as the client is concerned”
 
Tech Lead
"fields" just sounds like API talk
 
Me
but the client has made an API call
 
Tech Lead
the client hasn't made an API call though
if those prerequisite checks fail then no API has ever been involved
and even if it has, why would the client need to know anything about an API?
are you talking about the browser client?
 
Me
isn't it
client -> OrdersAPI -> our library {fail checks} -> error status to the client
 
Tech Lead
sorry i thought you were referring to the OrdersAPI as the client in this context
which it is
our package shouldn't know that it's being used in an API., that's the whole point of this change
 
Me
it's a black box for the caller. The user shouldn't know that it's using a library. The code could all the be in the same place as far as it is concerned

Then after more discussion, he is adamant that something could use our library in future so then there’s 2 usages, an API and non-API. So it cannot have API related stuff in it.

But our intention was to have a separate space for our team to maintain, we have never discussed it being used by anything other than the API. The early discussions was to have our repo that was an API.

Daniel
tbh I don't immediately think API when I see "field" I think it's fine
 
Me
he did say the message could just be
"‘Date of Birth’ is missing"
Which might be better but then wouldn't you want all the messages to be consistent. However, I guess someone could update the OrdersAPI repo with a new message style, and then forget about ours.
 
Daniel
you make a good point about consistency though, the API should be consistent regardless of where the code lives

It’s a really trivial argument, but I think this is just the beginning of many debates. Sometimes I think we like adding loads of complexity early on then work doesn’t get done.

Report API fail

A tester says they are running a Test Case where they need to generate a report using our software. This report utilises a third-party service. The report fails to generate.

There should be errors displayed when you view the details, but it’s completely blank. So if they have correct data, then it’s a bug because it doesn’t work. If they don’t have correct data, then it’s a bug because it doesn’t tell the user what the problem is. It’s a bug either way.

Becky, a Senior tester:

Asks him if he has the correct data. Completely misses the point.
Then she posts a follow-up question asking him if he has gone directly to the third-party website to get the information. Completely misses the point.

No, Becky, the functionality is that our software contacts the third party API to retrieve this information. Manually going to the website and filling a form out by hand isn’t helpful, or acceptable. It isn’t going to make the test case pass is it?

“ok, we will pass the test because the website works. Nothing to worry about.”
Becky’s mind

Sometimes I think she tries to be dumb on purpose.

Exposing a Secret Team

There’s been quite a few times where projects have been scrapped, or switched to a completely different team.

A project which is making a library (that I reckon will be used by every team) quietly got abandoned, then reassigned to a different team. The reassignment wasn’t communicated either. I found out just by browsing the repositories, and saw one with similar functionality.

My team felt the need to use such a feature and so we posted in Slack asking if anyone had plans/advice. Later that day, a big announcement was sent out, stating that people will need this, and teams should contact them for further info.

We contacted them for further info, then they said they don’t have an API because they didn’t consider people would want to use it just yet.

Are they having a laugh?

Why does it take people to ask about a project to then publicise the existence of it. Then it turns out it wasn’t even ready for other teams to even consider using.

The general advice to teams was to proceed “API first”, so that way dependent teams aren’t blocked. Then this team, whose entire existence is to work with pretty much every team – comes out with “we didn’t consider people would want to use it just yet”. Why were they working in secret?

Anyway, that’s even more work to block on our backlog then.

The API 2

I wrote in a previous blog (https://strangercodingtings.home.blog/2019/12/30/the-api/) about an API that we wanted but didn’t meet our needs.

Another month went by, and we contacted the team to get estimates when they plan on changing the API to actually be usable.

The response we got was that their project was finished, and all the developers have been reassigned to different projects.

Hang on! How can they write an API and not work alongside any team!? The whole point of it is to provide data to other teams, so how can other team’s not be involved?

It’s not like they didn’t know we wanted it, I was requesting data from them in the prior 2 months.

I’m not sure when they plan on scheduling this work in, but it’s just stupid.

Joined up working

I think it’s best if you have teams that are in the same location since meetings are easier to arrange and have fluid communication.

If you are in the same office, you can have ad-hoc face-to-face communication. You can all go into a meeting room and don’t need any conference-call equipment which can have all kinds of problems; disconnecting, low audio quality. Same time-zones means there are more hour slots available to arrange meetings in.

I’ve heard people imply that teams end up being distributed just so that the other offices feel like they “feel part of it”/feel integrated into the company. Yet giving them a dedicated project they are responsible for would probably achieve that better; they will have more responsibility/autonomy. Adding members from the main development office makes it feel like they are been supervised.

Many times, you rely on a third party of some kind (by third party, this could be another team within the company or a different company). Maybe the third party collects the data and you just retrieve it via an API. You don’t really care about how the data got there, just that you can use it and it works accurately. Your team that wrote the user interface feel like they have achieved something. The team that collated the data and provided the API feel like they have achieved something. The teams may only need to communicate for a minor part of it. The teams need to know the overall aim, and what parameters they need for the API. My point here is that you can have two different teams with some minor collaboration, but both feel like they have contributed massively to the overall goal of the project.

I think adding a remote worker for the hell of it is just inefficient. Unless they are exceptional and can’t be replaced by the talent you have locally, then its just adding in unnecessary inefficiencies and causing unnecessary bottlenecks (have to delay meetings due to time-zones), have to wait until the next working day to get a response, different countries having different National Holidays.

The API

In our current project we need some user data to populate a screen with the user’s settings. I ask the team responsible for this data if they have an API we can call. It shouldn’t have been a surprise to them because we are replacing existing software and the requirements are the same – we just need to implement it using different technologies.

So I email them with the requirements. I want to pass them a UserId, and I want them to send me back the User’s Configuration in return. Easy.

A few days later they send me a meeting invite.

On the meeting they said they didn’t understand the requirement. I then show them the UI designs, and tell them that I need the data in order to populate a form for a particular user.

Two weeks later I get another invite. They still don’t understand what we want. So another team member explains to them.

The next day I get an email with their new design. I can call their API with an ID related to my application, then I have to do a separate API call but I can’t specify a user. The format it comes back in is JSON, but it’s not really conforming to the standard.

So you may expect some JSON about a film to look like this:

    {
        "title": "Gravity",
        "info": {
            "directors": ["Alfonso Cuaron"],
            "actors": [
                "Sandra Bullock",
                "George Clooney",
                "Ed Harris"
            ]
        }
    },

but instead they said they want to send this:

    {
        "title": "Gravity",
        "info": "{directors: [Alfonso Cuaron], actors:[Sandra Bullock, George Clooney, Ed Harris]}"
    },

So you can’t have nested objects which JSON is designed for. Instead, you just have 2 fields with everything smashed into one text string. Why?

Ignoring that though, after 3 months, they finally email to say it is ready. So I look at their Swagger documentation which shows all the API calls in a website, and even has a button that can trigger an API call so you can see an example response. “Brilliant” I thought, I can understand what they have done without writing any code or using a tool like Postman to send calls. It is simple as clicking a button. I click the button…but the message fails to send.

I then send an email, informing them that this doesn’t work. The developer says something along the lines of “we are in the process of changing the API”. What do you mean? I waited 3 months and you are saying it’s not ready – an hour after telling me it was ready!? He did get the Swagger documentation updated before the day was over, but I just don’t understand how it wasn’t updated as they were actually making the changes.

So after 3 months, we get an API that isn’t even suited to our needs. This is just madness because we will be the only consumer of at least one of the calls they implemented. Therefore, the API should be driven by our requirements. We shouldn’t be making two different calls, then doing some jiggery-pokery with the data, when it is easy for them just to send it back in the format we want.