Five Practical Tips for Building Your Java API

Increasingly, Java developers are building APIs for their own apps to consume as part of a micro-services oriented architecture, or for consumption by external services. At Stormpath we do both, and we’re expert in the “complications” this can create for a development team. Many teams find it difficult to manage authentication and access control to their APIs, so we want to share a few architectural principles and tips to make it easier to manage access to your Java API.
For a bit of context: Stormpath at its core, is a Java-based REST+JSON API, built on the Spring Framework using Apache Shiro as an application security layer. We store user credentials and data on behalf of other companies, so for us security is paramount. Thus, my first requirement for these tips is that they help manage access to your Java API securely.
We also evaluated tips based on whether they work well in a services-based architecture like ours, whether they benefit both internal and public APIs, and whether they offer developers increased speed and security.
On to the fun part!

Secure Authentication Requests with TLS

I like to think of an API as a super-highway of access to your application. Allowing basic authentication requests without TLS support is like allowing people to barrel down your highway… drunk… in a hydrogen powered tank… When that requests lands, it has the potential to wreak havoc in your application.
We have written extensively on how to secure your API and why you shouldn’t use password-based authentication in an API. When in doubt, at a bare minimum, use Basic Authentication with TLS.
How you implement TLS/SSL is heavily dependent on your environment – both Spring Security and Apache Shiro support it readily. But I think devs frequently omit this step because it seems like a lot of work. Here is a code snippet that shows how a servlet retrieves certificate information:
public void doGet(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException {
X509Certificate[] certs = (X509Certificate[]) req.getAttribute("javax.servlet.request.X509Certificate");
Not a lot of work. I’ve posted some links to different tutorials at the bottom if you’re new to TLS or want to ensure you’re doing it right. Pro tip: Basic Auth with TLS is built into Stormpath SDKs.

Build Your Java Web Service with Spring Boot

Spring Boot is a fantastic way to get a Java API into production without a lot of setup. As one blogger wrote, “It frees us from the slavery of complex configuration files, and helps us to create standalone Spring applications that don’t need an external servlet container.” Love. It.
There are a ton of tutorials (see below) on building Restful Web services with Spring Boot, and the great thing about taking this approach is that much of the security is pre-built, either through a sample application or a plugin. SSL in Spring Boot, for instance, is configured by adding a few lines to your file:
server.port = 8443 server.ssl.key-store = classpath:keystore.jks server.ssl.key-store-password = secret server.ssl.key-password = another-secret
Stormpath also offers Spring Boot Support, so you can easily use Stormpath’s awesome API authentication and security features in your Spring Boot App.

Use a Java API to Visualize Data…About your Java API

So meta. Because APIs are (potentially, hopefully!) managing lots of data, and the availability of that data is critical to downstream connections. For APIs in production, analytics and monitoring are critical. Most users won’t warn you before they start load testing, and good usage insight helps you plan your infrastructure as your service grows.
Like other tech companies (Coursera, Indeed, BazaarVoice), we use DataDog to visualize our metrics and events. They have strong community support for Java APIs, plus spiffy dashboards.
Also, we project our dashboards on a wall in the office. This certainly doesn’t replace pager alerts on your service, but it helps make performance transparent to the whole team. At Stormpath, this has been a great way to increase and inform discussion about our service delivery and infrastructure – across the team.

Encourage Your Users To Secure Their API Keys Properly

The most terrifying thing that happens to me at work is when someone emails me their Stormpath API key. It happens with shocking frequency, so we went on a fact-finding mission and discovered a scary truth: even awesome devs use their email to store their API key and/or password… and occassionally accidentally hit send. When these land in my inbox, a little part of me dies.
Some ideas: – Make your API key button red. I’m not above scaring people with a red button. – At Stormpath we encourage storing the API key/secret in a file only readable by the owner. You can instruct your users to do this via the terminal, regardless of what language they are working in. Our instructions look like this (for an api key named
Save this file in a secure location, such as your home directory, in a hidden .stormpath directory. For example:
$ mkdir ~/.stormpath
$ mv ~/Downloads/ ~/.stormpath/
Change the file permissions to ensure only you can read this file. For example:
$ chmod go-rwx ~/.stormpath/

Stormpath Makes API Authentication, Tokens and Scopes Easy

Finally, a shameless plug: Stormpath automates a lot of functionality for Java WebApps. Our API security features generate your API keys, manage authentication to your API, allow you to control what users with keys have access to via groups and custom permissions, and manage scopes and tokens.
We lock down access with awesome Java security infrastructure. Stormapth for API Security and Authentication and our API Authentication Guide. These features work with all our Java SDKs for Servlets, Spring Boot, Apache Shiro and Spring Security and will save you tons of time.
As ever, feel free to comment if we missed anything or you have additional suggestions. If you want help with your Stormpath setup, email and a technical human will get back to you quickly.


TLS Tutorials & Sample Apps

Spring Boot your REST API service