API Testing Glossary

API Testing Glossary

I’ve been doing a fairly deep dive on API testing over the last several month, both as part of the project I am currently working on and as part of some courses I am preparing. As with any specialization there is a lot of terminology that goes into it and so I thought I would put together a post that summarizes a number of definitions related to API testing.

Many of these definitions can have different meanings depending on the context you are working in and they are used by your specific team, so don’t take this as definitive. They are just the way I have explained them to myself so that I can better understand and conceptualize them. By defining these terms I am better able to wrap my mind around them and to use them to do better testing.  Hopefully they help you out too in your testing journey

REST

Acronym for REpresentation State Transfer.  This is a protocol that is based on the dissertation of a guy name Roy Fielding. Obviously there is a lot that goes into this, but in really simple terms, a RESTful API is one that consistently applies actions (verbs) like GET, POST, PUT and DELETE to resources (nouns) which are usually a url that may have some parameters.

Further Reading:

Martin Folwer’s take on using REST well

Ruben Verborgh has a good explanation on Quora

Hypermedia

People will argue about this (surprise), but some say that an API is only truly RESTful if it uses a hypermedia approach. Hypermedia means that the server tells you what resources are available for you to use. Every request to the server should tell you what other resources and actions are available to you on objects that are related to the request you just made.  Sounds confusing? You are already pretty used to it. You came on this web page and there are number of links here that allow you navigate to other places on the web. When we simplify it down, that is really all hypermedia in an API is doing. It is telling you some other links (endpoints) and actions that you can use in the API.

HATEOS

Speaking of Hypermedia, let’s just make up a big long hard to say acronym that describes it’s usage. HATEOS stands for Hypermedia As The Engine Of State and is just a way of making people argue about pronunciation saying that your REST API uses Hypermedia.

GraphQL

It’s new! It’s exciting! It shall rule the world! Ok, in reality we like to get excited about new things in the tech space, but GraphQL is just another way of specifying an API. It is a query language that helps to optimize some things in network API calls and so for applications that have high performance requirements it can be very helpful. It is a bit more complex and rigid then REST though.

Idempotent

Big word for saying that every time you perform a call you get back the same result. I’ll give you a silly example to help you remember.  Think about putting snow tires on a car. Once you have them on you have a car with snow tires. Now if you repeat that ‘request’ you will end up with the same thing. A car with snow tires. In an API this would be a PUT call.  No matter how many times you send the call (with the same parameters), it should always give you back the same result.

Safety

Speaking of idempotency, a GET call is idempotent (you get the same result every time you execute it), but it has an additional factor called safety.  Safety just means that nothing changes when you issue the command. Let’s use a silly example again. Imagine a bookshelf.  You bend your head sideways a read the title off the spine of a book. Nothing has changed and no matter how many times you do that nothing will change. This is an example of a safe call.

Verbs and Nouns

No this isn’t English class, but we do sometimes talk about nouns and verbs in APIs. Verbs are the actions that an API can do (like GET, POST, PUT, DELETE) and the nouns are what the API acts on (resources usually represented by url endpoints)

Services (micro-services)

Buzzword time. So what is a micro-service? Well, it is a service that is very small, or uh, micro sized (see what I did there?). And a service is just something that does stuff and that lets you tell it how to do stuff (usually through APIs).  See it doesn’t have to be hard! Let’s use an example to get a better handle on it.  You want to create a meme (because you are that kind of cool) but photo editing is just to passe for you.  If only you had something you could send a command to that said ‘generate a cat meme for me with these words.’  Well if you did, that would be an example of a service – memes as a service in fact. You give it some commands.  It does something for you and produces an output for you based on the commands you gave.

Micro-services is just an architectural pattern that tries to have a number of services that can each do one specific thing. These various services can then talk to each other through the defined APIs. The micro part just means that each service has a limited number of tasks that it can do. So you might break down a customer facing service into a number of micro-services that each do one particular part of the overall task at hand.

All good things must end – including this list

I’m sure there are other terms to define in API testing. If there are any you find confusing, let me know and perhaps I’ll add to this list over time. Maybe I’ll even get ambitious and make this into it’s own page on the site. We will see.

Let me know what you think of these definitions!

 

Advertisements

How to do Demos?

How to do Demos?

I’m not sure how I feel about doing demos for the ‘higher ups’ in the company. It seems that when we do a demo, we end up with a carefully crafted environment, that perhaps has a few hard coded values in place. It runs on a local developer’s machine with code that has not yet been put up for review. We can run through aspects of the feature and show what it can do, which is good in that it allows for feedback on things.

But there is a downside too.

Have we got accessibility in place?  Is the code fully localized? Do we have a bunch of edge cases that we didn’t demo to clean up?  What about those hard coded variables we put in place to make the demo work? What happens when that code gets off the developer’s machine and out into the wild? How will it perform under real life loads and stresses?  There can be a LOT of work left to do on something that was shown in a demo, but does that really come through?

It seems like what can happen sometimes is we put our best foot forward in a demo, but we don’t show the things that are broken. We might mention some of the additional work that we need to do, but at the end of the day a picture is worth a thousand words.  When someone sees a ‘working’ demo, and then hears about a few bullet points of additional work, what will they walk away from the meeting feeling?

‘Oh this is almost done’

Is it though?

I think a lot of demos leave people with a false impression of the state of the feature, and this can lead to problems. It can lead to schedule pressures – after all it looked almost ready last week so why isn’t it released yet? This can really get bad if people start talking to customers or even just internally ‘bragging’ about the feature.

Solution

I wish I had a magic solution, but I don’t. Well, I guess I do have one – don’t do them – but perhaps that is a bit extreme. I was just struck by the thought that this can be a problem, and I still need to think more about what can be done about it.  Any thoughts?  Have you ever seen this problem on teams you’ve worked with?