RSS

Tag Archives: REST

Web API Design Part Nine: Versioning

30 Sep

Episode 95

Today’s episode is sponsored by the rain in Amsterdam and werewolves. It’s my second trip here within last two weeks with the initial goal of attending AWS trainings and some sightseeing, but AWS canceled one of these a day after my company bought non-refundable plane tickets and booked the hotel, so… more emphasis on sightseeing, or rather sitting in the coffee shop waiting for better weather. Why werewolves? Well, because in this installment of our long-running series on API design, we will talk about versioning and I find the werewolf a decent allegory to represent breaking (or tearing) changes in API that leads to a dilemma: which versioning strategy should be employed. And because I like fantasy themes for my articles.

aleksandr-nikonov-the-werewolf-by-niconoff-d59dlra

Image by Aleksandr Nikonov

There are many approaches to versioning with pros and cons and it’s difficult to definitively choose one or the other. We will explore possibilities of how to version and,  where to actually put the version information, including URI, parameters, content negotiation, custom headers, or… nowhere at all. We are going to talk about breaking and non-breaking changes and various considerations and hints relevant to helping clients of your API deal with the evolution of our system in a bearable way.

Shapeshifting

Before we start to multiply API version, we should consider whether we really need it. Backward compatible, or non-breaking changes should not Read the rest of this entry »

 
2 Comments

Posted by on September 30, 2018 in API, Technology

 

Tags: , , ,

Web API Design Part Eight: HATEOAS

08 Aug

Episode 93

Temperatures around are deeply disturbing when I’m writing this post, so I decided to banish myself to a place with air conditioning and cold brew coffee. Time from the last post is a bit longer than expected, but as an excuse, I wrote (almost) two different articles meanwhile on the subject of microservices, that will be hosted on other blogs. I will link them here later. Digression aside, today we are going to talk about Hypermedia as the Engine of Application State, also known under a lovely acronym HATEOAS.

diablo_ii_fanart_by_alswns3421-d99299k.jpg

The previous article, about security, has a brief reference to a soundtrack of a classic game Diablo II, and so has the art I used on the slide about HATEOAS on my API design presentation. Remember the boss of act III, Mephisto? Apparently, any serious demon needs an appropriate title, in that case, it was: Lord of Hate. Hate, HATEOAS, you know, it worked well together. Okay, I’m over with digressions, I promise. Let’s get down to Dungeons of Hate… I meant, let’s get down to business.

The Overlord

I meant: The overview… HATEOAS is a part of REST architectural style. It might be considered a high-level part according to Richardson maturity model, as Read the rest of this entry »

 
2 Comments

Posted by on August 8, 2018 in API, Technology

 

Tags: , , ,

Web API Design Part Seven: Security

27 Jun

Episode 92

Short digression first. I’m currently sitting in a lovely and almost on-time train from Wrocław to Kraków in order to get to Devoxx PL conference and rant again about, guess what, web API. I was assessing which part of the design should I write about today, put on the headphones and kicked my usual collection of writing music mainly composed of video games soundtracks. The first track that pops up randomly is “Diablo II – The Wilderness”. It’s dangerous out there, I thought, API security it is then.

Welcome to the next chapter of our journey through the vast realms of web API. We have wandered far away from home now, and the wilderness is getting scary and dangerous. Let’s see what we can do to stay safe here.

ee5972e76e3e7b0be1925b6a334dc58a-d5hzy0x

It’s not the first security focused article here, but probably the most technology agnostic. In episode 63 we tackled some hands-on examples of security aspects in Spring framework. In episode 77 we looked at details of AWS IAM – Identity and Access Management while following in episode 78 with other AWS services related to security.

Today we will talk about authentication and authorization ways in web APIs, keys, JWT, OAuth, TSL, throttling, threats and attacks and explore some general tips on Read the rest of this entry »

 
1 Comment

Posted by on June 27, 2018 in API, Technology

 

Tags: , , , , ,

Web API Design Part Six: Cache

20 May

Episode 91

In the previous episode of this series, we talked about communicating response status through HTTP codes and error objects with several fields describing what the hell happened and how to deal with it. It was the last part of the core business aspects of web APIs, those that are the most visible to our clients and connected with a product domain. Today we will start a second big part of our journey, supporting aspects – things that are more generic, technical, a bit in the background and not always noticeable from a business perspective, but nonetheless important. First topic here will be cache.

hostile_hideout_by_nele_diel-d5znf4m

As we might remember from an episode about the origins of REST, cacheability is one of six fundamentals of REST. The idea is that every response from the server must contain Read the rest of this entry »

 
1 Comment

Posted by on May 20, 2018 in API, Technology

 

Tags: , , , ,

Web API Design Part Five: Status and Error Handling

22 Apr

Episode 90

In the previous installment of the web API design series we looked into ways of implementing various operations on object collections: filtering, searching, sorting and pagination. We also tackled ways to parametrize HTTP requests in order to employ mentioned operations.

e0yFDA1.jpg

After an article focused on requests, let’s work on our responses. We will talk about HTTP codes, which of them are actually worth using and how to use them. Before delving into specific codes, let’s talk about how we should inform our API consumer about problems.

There is a dragon in the server room

The dragon set the server on fire and we have troubles with processing your request, please try again late. Sometimes bad things happen. Read the rest of this entry »

 
2 Comments

Posted by on April 22, 2018 in API, Technology

 

Tags: , ,

Web API Design Part Four: Collections

28 Mar

Episode 89

In the previous episode we talked about core concepts of web API designs, including resources and representations, naming, relations, functions and sanity checks. We looked at what should be the expected behavior of HTTP methods regarding operations on single objects and collections.

f59368ef274b9329435f2f11683bd4f4--fantasy-art-landscapes-concept-art.jpg

Today we will focus expand on the topic of collections, namely: filtering, sorting and pagination. While talking about filtering collections, we will look at filtering fields in particular single objects. In order to do that Read the rest of this entry »

 
1 Comment

Posted by on March 28, 2018 in API, Technology

 

Tags: , , ,

Web API Design Part Three: Core Concepts

08 Feb

Episode 88

Two months ago, we started with motivations behind web APIs and looked at their design from UX point of view. The important conclusion was, that API and its ecosystem is to developers what GUI is to regular web applications users. A month ago, we looked from the scientific point of view at the properties of a modern web systems architectural style, REST, through the lenses of Roy Fielding’s famous Ph.D. dissertation.

adam-kuczek-simra-web.jpg

Having those foundations, today we are going to get our hands dirty and talk about how to actually get the work done. Today we will talk about resources and representations, naming, relations, HTTP methods, collections, functions and sanity checks.

Resources

REST web API is built around exposing representations of resources being part of our system. The distinction is important: resource is some piece of data stored on our system or accessed ad hoc from somewhere else. It might be a record in a relational database, a document in NoSQL, a file on disk, or a stone tablet with hieroglyphs stored in an ancient tomb. Read the rest of this entry »

 
3 Comments

Posted by on February 8, 2018 in API, Technology

 

Tags: , , , ,

Web API Design Part Two: The Origins of REST

14 Jan

Episode 87

What is REST, or what does it mean to be RESTful? It seems to mean something a bit different for everyone, when looking at various API implementations and their documentation. When examining different materials on the art of web API design, one eventually stumbles upon one particular name. Roy Fielding, a computer scientist who was member of the team behind HTTP 1.1 and URI specifications. During this undertaking he created a set of principles around HTTP object model that culminated in his PhD dissertation “Architectural Styles and the Design of Network-based Software Architectures” published in 2000. Probably not too many people in software development industry read PhD dissertations, but I’ve decided to do that, and extract the essence in this article.

old-sage.jpg

First part of the thesis introduces various preliminary notions relevant in consequent parts. We learn the definition of Software Architecture and its elements including components, connectors and data. Then we proceed to Read the rest of this entry »

 
4 Comments

Posted by on January 14, 2018 in API, Books, Technology

 

Tags: , , , ,

Spring Web Basics

09 Mar

Episode 60

Here is the second part of Spring back-end series for beginners. Part zero appeared half year ago, and was focused on Angular front-end. Part one was two weeks ago, and consisted of some basic concepts of Spring framework including inversion of control, dependency injection, beans, configuration and profiles. Today we are going to look into Spring web, in particular web services and handling incoming HTTP requests. There will be no fancy front-end stuff this time, just naked request and response.

steampunk_spider_lamp_by_catherinetterings-d6ugb5v

As usual the introduction to the topic and going over basic concepts might well be at least one separate article but let’s try to do all at once. We will cover the concept of HTTP protocol, servlets, web services, REST and JSON. If you would like to play with complete application working out of the box, visit my GitHub project Spring Angular Intro. This tag corresponds to project state at the time of writing this article.

Foundations

HTTP or Hypertext Transfer Protocol, belongs to the application layer of Internet Protocol Suite, so it’s the highest-level layer above transport layer (like TCP), network layer (like IP) and link layer (like Ethernet). HTTP request contains Read the rest of this entry »

 
4 Comments

Posted by on March 9, 2017 in API, Spring, Technology

 

Tags: , , , , ,

API management tools

08 Dec

Episode 47

Long time ago, the Internet was full of proud and secluded applications, that relied on themselves to provide service. However, services were becoming more and more complicated, also technologies and protocols for connecting with other applications became more standardized. It became obvious that collaboration and specialization is required to survive. Applications thus started to be more specialized, talk to each other much more, and the level of digital interconnection skyrocketed. Along with that, did the market of solutions for managing web APIs.

Do I need API?

Most likely you do. Imagine a big corporation that is building HR system. They want the module related to business travel for planning and reporting. Is there a point in writing everything from scratch? If you plan travel, let’s ask someone who is already good at it. If you want to buy a ticket from A to B, there are companies that provide travel meta search service, both via website and API.

internet-of-things_high_res.jpg

Those companies need data, so they ask someone who possess it – bus and train operators, airlines, car rentals and perhaps other travel meta search companies. Maybe, when planning travel, especially the end points, we might want to specify an address. How do we know that address is correct? We should ask someone who Read the rest of this entry »

 
5 Comments

Posted by on December 8, 2016 in API, Technology

 

Tags: , , , ,