Monthly Archives: January 2015

Setting Up HTTPS For Spring Boot

Over a year ago I wrote a post titled “Setting Up HTTPS For Spring Boot.” At the time, the path to running your Spring Boot web server with HTTPS was not so easy to find. Now, a year later, Spring Boot is on version 1.2, and the need for so many people to easily setup HTTPS has driven a big change in how you accomplish this.

So now, and without any further ado…
Let’s SSL with spring boot one point two!

If you configured SSL using the previous post, the new technique is like so: In your application.properties file, add

server.port = 9000
server.ssl.key-store = keystore.p12
server.ssl.key-store-password = mypassword
server.ssl.keyStoreType = PKCS12
server.ssl.keyAlias = tomcat

that’s it!

Seriously! You can stop reading now! 🙂

But if you want more information, you can see the new directions for setting up SSL here, see the section on “Configure SSL.”

Enjoy your new and simpler configuration!

1 Comment

Filed under Software Engineering

You Don’t Have To REST

This is the last of my thoughts on REST (for the time being) after spending a few weeks doing some research and giving it some thought. See the previous two posts for more background.

What About Change?

According to Fielding: “You can’t have evolvability if clients have their controls baked into their design at deployment. Controls have to be learned on the fly. That’s what hypermedia enables.”

I didn’t quite get this at first. That’s the whole point of versions: clients DO have their controls baked into their design at deployment time, and I don’t have any power over how users of my service are going to write their software.

Yes, We Can (Change)

So I did some more research, and found another discussion with Fielding. Take a look at the discussion, especially at comment 21 (trimmed here for brevity):

“Of course the client has prior knowledge. Every protocol constitutes prior knowledge that the client must know in order to make use of that knowledge. REST is intended for long-lived network-based applications that span multiple organizations. If you don’t see a need for the constraints, then don’t use them. I have no problem with systems that are true to their own architectural style.”

As Usual: Do What Works For You

I think the idea here, and it’s starting to make more sense after digesting it, is that

  1. REST may still require a priori knowledge on the side of a client to use
  2. REST is not the end-all of API structures and not appropriate to all applications

It is cool, yes, and people like it. But you don’t have to sweat versioning, or sweat following every REST constraint. You can incorporate ideas you find useful, and mention which REST constraints you follow as a shorthand for communication about the architecture of your API.

Your API should do what works for your product. You should do what works for you.

Leave a comment

Filed under Uncategorized

More On REST Versioning: Your API Is Not Your Schema

This is a follow up to last week’s post about REST versioning.

When we talk about versioning of API’s, we need to actually clarify something. You can version an entire API or version individual resources. When you change the schema of returned objects identified by a URI, that’s a problem with individual resource version. If you change the available endpoints and operations, that’s a problem with API version. The two should not be conflated. (see discussion points here and here.)

I think that’s what Roy Fielding meant when he said “Don’t version your API.” The API is your set of endpoints and operations, and they are identified dynamically by providing links (controls) dynamically. There’s a distinction between that and versions of data structures returned by your API. The latter are versioned by content type, since if the structure changes, it’s a different format of data just as an XML document is a different format from a PNG.

So let’s take a step back and ask: Does it even make sense to have different versions of these resources? If you changed the format of a certain resource, certainly an un-updated client that doesn’t know about a new schema could still use of the old format and ask for it by name, and new clients would want to use the new format. But in your server side code, you’ll still have to have two different DTO classes for each representation. I would argue that the new version is actually a new resource representing new information, and should therefore have a new URI entirely.

With this way of thinking, you could advertise the old object/URI as deprecated, and your versioning becomes simply deprecating URI’s that are not accessible from your main API over time. Any clients that access URI’s directly (i.e. not through the hypermedia controls you provide) would be responsible to update themselves.

What do you think? Is this a reasonable approach to versions and your API? As a thought experiment, what do you think would happen if you used your API version to version your data structures?

Leave a comment

Filed under Software Engineering

How To Version Your REST API

So the other day I was playing with writing a new REST API. Everything was going great until I decided that I wanted to try changing the structure of a certain resource (say, change the response for resource at /user/1 from {name: jason} to {username: jason}). I had a number of integration tests, but figured I could migrate my integration tests incrementally, just like third party applications would have to do in the real world. I just had to be able to respond to requests for both versions. This immediately raised the question: “How do you version your API?

If you spend just two minutes with Google, you’ll find that this is a question that gets asked a LOT, and has different answers depending on whom you ask.

In the URL!

One way to version your API is to put a version in your URL, such as mysite.com/v1/thing/id. You’d be in good company. Atlassian does it like that. Google does it too. A format like this is easy to recognize and easy to test.

This is the most highly voted approach from the popular StackOverflow question. And this is a common sentiment in Hacker News: “I can’t recall a single API I’ve seen or used that took the academic approach of using HTTP Accept headers. All of the major REST APIs I’ve seen have used API key X-* headers and most of them use versioned URIs.”

In the Headers!

Putting version information in the HTTP Accept header (so the client says what they can Accept, and the server responds with the appropriate Content-Type) seems like a pretty common answer. It seems to be accepted as the “more correct” approach at the expense of being more academic and less practical. There are even well reasoned arguments why this is the best way.

At first I was wary of this approach because I worried about not being able to detect the header in the request logging, and so wouldn’t be able to tell when to retire the old service. But it turns out you can log requests and record header information, especially if you are fronting with apache.

They’re All Wrong!

Ok, so we have a couple approaches (not to mention using query parameters), but there is a third approach: they’re all wrong. When this big question of how to version a REST API came up to Roy Fielding (inventor of REST), his response was “Don’t.”

According to Fielding: “You can’t have evolvability if clients have their controls baked into their design at deployment. Controls have to be learned on the fly. That’s what hypermedia enables.”

Where Do We Go From Here?

My opinion at this point in time is to use the Accept Headers for content negotiation rather than put version information in the url or query parameters. It just seems like the right way to do it and is easy enough on client and server.

The question for you is: How do YOU version your API? Is it possible, as Roy Fielding implies, to write a versionless API where every field is purely discoverable? I’m skeptical but would love to be shown a better way.

Leave a comment

Filed under Software Engineering