I recently encountered an interesting problem while sketching out a RESTful API for a side project with the JSON API specification. I’m definitely not the first person to run into this problem, but it ended up being a great thought exercise for designing APIs and better understanding the client-server relationship. Read more on Leveraging the Boundary Between Client and Server in a REST API…
API
Exporting Server-Side Types and Endpoints to Ember
Keeping the client and server in sync can be difficult while developing a web app. That’s particularly true if you are using text-based data such as JSON in your API calls (though the flexibility and readability of JSON over binary data should not be disregarded).
Read more on Exporting Server-Side Types and Endpoints to Ember…
Be Explicit with Your API’s Data
I recently managed to take a feeling I’ve had about API design and formulate it into a specific recommendation: Be explicit about state when crossing system boundaries.
Read more on Be Explicit with Your API’s Data…
4 Types of APIs and When to Use Them
Most apps today draw a strong line between the server and the client. The client, maybe a single-page web application or a native mobile app, focuses on the user-facing features, while the server provides the data and a way to update it. Atomic has done a lot of projects this way, and we’ve found it’s a solid way to decouple the core business logic and database from different platforms.
Decoupling the client from the server means we can use an alternative back-end instead of the eventual production server. Several projects I’ve worked on have used this ability to keep development on the client moving forward, even though the actual production back-end wasn’t ready yet. Ryan wrote about the benefits of fake APIs like this a couple of years ago. But there’s more to swappable back-ends than fake APIs. Different situations call for different servers with different powers.
Read more on 4 Types of APIs and When to Use Them…
4 Pitfalls of Developing with APIs
Estimating software development efforts is hard. We’ve used a lot of different strategies, but the bottom line is that it’s hard to come up with a good estimate very often.
There are a few warning signs I have learned to look for that frequently indicate that my estimates might be off: Unfamiliar technology, vague requirements, or complicated or regulated business domains are common and typically very visible red flags that you’re probably already looking for. Today I want to focus on a warning sign that I’ve frequently seen ignored or underestimated: external services or APIs.
If you are building an application that is heavily dependent on another firm’s API, you should probably triple your estimate.
3 Benefits of Fake APIs
Developing an application and an API in parallel can be quite the tricky task. Often times, it can lead to misunderstandings and miscommunication between developers. This can cause a project’s progress to come to a screeching halt. The longer the misconceptions go unnoticed, the bigger the damage may be.
Framework Docs Are a First-Class Citizen
Documentation is a crucial part of any good API or framework. Despite this importance, it often gets neglected and treated as an afterthought.
I recently asked another developer how he always managed to put together such well-thought-out and complete documentation. His response was: “Documentation Driven Design (DDD): if your API feels clunky to document, it’s probably a bad design.” This reminded me of my first introduction to Test Driven Development (TDD). By breaking your code into smaller chunks and testing them first, you were immediately placed on a road traveling toward better design. Given how useful TDD has been for me, DDD seems worthwhile.
One of the main considerations that determines whether I use a framework is how complete and easy to understand the documentation is. But in my own hypocritical way, I’ve neglected good documentation principles on my own hobby projects and frameworks. Read more on Framework Docs Are a First-Class Citizen…
iOS Mirroring and Programmatic Airplay Selection
Currently, Apple limits access to AirPlay and mirroring capabilities in their public APIs. Developers are given a great deal of latitude in terms of what content to display but are limited in how and where that content is displayed.
On a recent project we needed more control over how and when content is displayed via AirPlay. Luckily for us we were not burdened by App Store Review Guidelines since it was a prototype and didn’t have to make it into the App Store.
So…down the Private API rabbit hole we went.
Read more on iOS Mirroring and Programmatic Airplay Selection…
State in Web Applications
The prevailing strategy of writing web applications is to write server-side code that renders the interface in full. Dynamic interaction, when needed, is achieved by playing tricks with the DOM using frameworks like jQuery or Backbone, but the majority of interactions happen via following links and receiving pages from the server. I’ll call this the CGI way, and there’s certainly plenty of fun to be had using it. You’re afforded a nice programming language on the server side with a plethora of tools to make your life easier, with JavaScript and its unique strengths and weaknesses providing variety on the client side. If you look at an app like the old Basecamp, it’s clear that you can make quality products this way. Despite this, I feel the approach is deficient.