CORS in Action: Creating and consuming cross-origin APIs (2015)

Preface

I first encountered cross-origin requests around 2006, when I joined Google and became the owner of the GData JavaScript Client. The GData JavaScript Client was a library that gave developers access to various Google APIs from JavaScript. The library itself was written in JavaScript, and the code was pretty straightforward...except for this little corner of code that made cross-origin requests to Google’s servers. This was before CORS existed, so this little corner jumped though crazy hoops to load data from Google’s APIs. From the developer’s perspective, the code simply worked. But between the request and the response was a dark and convoluted maze of code that was difficult to understand and debug.

So you can imagine my happiness when I discovered CORS. Here was a clean, simple, and standard way for making cross-origin requests. Instead of code that’s difficult to understand, I could have simple HTTP response headers. Instead of code that’s difficult to debug, I could have a single standard that worked across all browsers. I quickly set out to add support for CORS to Google’s APIs.

And that’s when the real fun started. While CORS uses HTTP headers to enable cross-origin requests, there are many subtle ways in which these headers can interact. It’s not as simple as adding an HTTP header to your server and calling it a day. And because CORS was such a new feature, there weren’t a lot of resources to guide me. Armed with the CORS spec, Wireshark, and a lot of patience, I spent the next few weeks building a flexible and configurable CORS library that could work for various types of requests. Based on that experience, I started contributing CORS knowledge to the community by participating in Stack Overflow and writing an article about CORS for HTML5Rocks.com.

That was almost three years ago, and in the years since, CORS has grown from a specification to a feature supported by most major APIs. You can find CORS support in APIs from Amazon, Dropbox, Facebook, Flickr, Google, and GitHub (to name just a few). This book distills those three years of experience into an easy and illuminating resource for learning CORS. My hope is that this book helps make CORS a little less daunting, and encourages you to add CORS support to your own systems. Open access to information is a cornerstone of the web, and CORS is one of the ways to enable this. The more developers become comfortable with CORS, the more it will become a part of the everyday vocabulary of the web.

About this Book

The idea behind CORS is simple: allow one site to make a request to another. It’s a fairly trivial thing to do from most programming languages. So why does there need to be a book about it?

Hidden behind this simple idea are a lot of complex concepts. While other programming languages have no restrictions on HTTP requests, things are different in a browser, where the browser’s same-origin policy prevents requests from different sites. CORS must balance the need to enable cross-origin requests while preserving the same-origin policy for sites that don’t use CORS.

Also, CORS has both a client- and a server-side component. For a cross-origin request to succeed, the client and the server must be in agreement. This is different from other web technologies. For example, CSS lives solely in the client-side code; there is no server-side component.

This book serves as an introduction to CORS and attempts to demystify the issues that make CORS complicated.

What this book will give you

Here is an overview of the topics this book will cover:

· CORS from the client— This book starts by looking at how to make CORS requests from JavaScript code. It introduces the XMLHttpRequest object, which can be used to make CORS requests. While the XMLHttpRequestobject may be familiar to JavaScript developers, the book focuses on what is unique about CORS. The book also covers alternative mechanisms for making CORS requests, such as images in canvas elements, media uploads, and using JQuery.

· CORS from the server— The server uses HTTP headers to control CORS behavior. HTTP headers can be used to indicate things like which HTTP methods are allowed, whether cookies can be included on requests, and whether cross-origin requests are allowed at all. This book takes an in-depth look at what these headers are and how they’re used.

· Debugging CORS requests— Because CORS has client and server components, it can sometimes be difficult to debug CORS issues when things go wrong. This book ends with a look at how to debug issues with CORS requests. It introduces such tools as the browser’s debugging tools, Wireshark, and Fiddler.

What this book won’t give you

This book isn’t an introduction to JavaScript or the web. This doesn’t mean you need to be a JavaScript expert. It assumes that you have a basic understanding of how the web, HTTP requests, and JavaScript work.

Although this book uses Node.js and Express for the sample code, you won’t find fully programmed CORS solutions for your specific language or platform (unless, of course, you happen to be using Node.js and Express). The core concepts of CORS are the same regardless of what web platform or programming language you use. The goal of this book is to give you the foundation for understanding CORS, so that you can then go off and implement it on your own platform.

How to read this book

Because this book is an overview of CORS, you can approach it from different perspectives:

· API owners— Whether you maintain an existing API or are building a new API from scratch, CORS is a great way to extend your API’s reach.

· API consumers— Building dynamic sites on top of APIs can sometimes be difficult. CORS can make this easier by giving developers a pure JavaScript mechanism for making API requests.

· JavaScript developers— Even if you aren’t making CORS requests, JavaScript developers can benefit from understanding the basics of how XMLHttpRequest and CORS work. Most modern web pages are built on top of asynchronous HTTP requests (AJAX), and it’s useful to have CORS as another tool in your toolbox.

Roadmap

This book is divided into three parts. The first part looks at how to make CORS requests from the browser. The second part looks at how to add CORS support to a server. The third part looks at how to debug CORS requests.

Part 1: Introduction to CORS

Chapter 1 begins by giving an overview of what CORS requests are and how they work. It then dives into CORS with an example that makes cross-origin requests to the Flickr API.

Chapter 2 introduces the XMLHttpRequest object, which can be used to make cross-origin requests. Next, it covers the XDomainRequest object, which is used to make CORS requests from Internet Explorer 8 and 9. Then it covers other places where CORS shows up, such as canvas images. Finally, it looks at how to make CORS requests using JQuery.

Part 2: Implementing CORS

Chapter 3 switches gears to see how a server can be configured to support CORS. It takes a closer look at the role that the client code, the browser, and the server play in the lifecycle of a cross-origin request. It introduces the Access-Control-Allow-Origin header, which is how a server indicates that it allows cross-origin requests.

Chapter 4 introduces the concept of a preflight request, which is a small request that asks the server for permission to make the actual CORS request. It covers how the preflight request fits into the CORS lifecycle, and introduces a new set of HTTP headers for controlling the response.

Chapter 5 looks at how to include user credentials such as cookies on the request. It also shows how the server can grant permission to the client to read certain response headers.

The preceding chapters set the foundation for using CORS from the server. Chapter 6 expands on these ideas by providing a set of best practices for implementing CORS on your own server.

Part 3: CORS in practice

Chapter 7 looks at how to debug CORS requests when something goes wrong. It introduces tools like the browser’s debugging tools, Wireshark, and Fiddler, which can be used to monitor and diagnose CORS issues.

Appendixes

Appendix A provides a reference for all the CORS-related headers. Appendix B looks at how to set up Node.js and Express, which are used throughout the book for the sample code. Appendix C takes a closer look at CSRF issues, and how they relate to CORS. Appendix D looks at other cross-origin request techniques.