How Square makes its SDKs
At Square we leverage the OpenAPI standard, Swagger Codegen & GitHub to build and deliver our client SDKs in a scalable way.
Heads up, we’ve moved! If you’d like to continue keeping up with the latest technical content from Square please visit us at our new home https://developer.squareup.com/blog
The developer platform team at Square is a little different than most. Rather than build separate APIs for our developer products, we focus on exposing the APIs that our first-party product use to create a seamless experience for developers. We have many upstream teams that are stakeholders in our external facing APIs, constantly wanting to expose new features and make improvements. This was an important factor when deciding how we should build our SDKs; we did not want our team to be a bottle-neck, where product teams would have to wait on us to finish updating SDKs before releasing new features. The primary way we avoid that is with SDK generation.
Instead of writing each of our SDKs by hand (which would not only be time consuming, error prone, and slow down the release of new features into the SDKs) we use a process that relies heavily on SDK generation. There are many flavors of SDK generation out there, so if you are looking into adopting a similar method for your SDKs, be sure to look at a range of the possibilities and find the right one for you. Our preferred flavor uses the OpenAPI specification to define our API endpoints and Swagger Codegen to programmatically generate the code for the SDKs.
We use the OpenAPI standard to define our APIs. For us, this is a
JSON file that defines the url, what kind of HTTP request to make, as well as what kind of information to provide, or expect to get back for each our API endpoints. Our specification is made up of 3 main parts: general info/metadata, paths, and models.
This part of the spec contains some of the descriptive information for the API overall, like where you can find licensing information, or who to contact for help.
These describe the individual endpoints (or URL paths) for the API. It describes what kind of
HTTP request to make, how it should be authorized, and what kind of information you should add to the request, and what you should expect to get back. In the example below, you can see that it is a
POST request, there are a couple required parameters in the URL, another one in the body, and you get back a
The models describe the different objects that the API interacts with. They are used primarily for serializing the JSON response from the API into native objects for each language. In this one,
CreateRefundResponse, you can see it has a couple other models that it is comprised of, as well as a description and even an example of what the response looks like.
You can see the most recent version of our specification to date version in our Connect-API-Specification repo on GitHub.
The specification is an important part of our generation process, as it is the source of truth about how our APIs work. When other teams want to expand their APIs, release new APIs, or just increase the clarity of a model description, they can make an edit to this single file and have their changes propagate to all of the client SDKs. We actually generate most of our specification from the files that describe the internal service to service communication for even more process automation and easier changes.
Now that we have the specification for our APIs ready to go, how do we turn it into a client facing SDK? The answer is Swagger Codegen. Swagger Codegen is an open source project supported by Smartbear (just like the other Swagger tools) that applies your Open API specification to a series of templates for SDKs in different languages with a little configuration sprinkled in.
The templates use a language called mustache to define their parts, and for the most part look and read like a file in the desired language. The one below is part of the templates for out PHP SDK. You can see that useful things like code comments are auto generated as well, so that the end SDK can have built in documentation, snippets & more.
These are actually much less complex, and are essentially small
json files that describe aspects of your SDK, generally around how it fits into the relevant package manager.
Our process has evolved quite a bit, with tools like Travis CI making big impacts in the process. You can use CI & CD tools to make the process more automated but be sure that you have a good suite of test coverage to help prevent unexpected changes from creeping into your released code.
Hope your enjoyed the look into our SDK generation process. You can also see a recorded talk I gave at DevRelCon about the subject here. If you want to learn more about our SDKs, or other technical aspects of Square, be sure to follow on this blog, our Twitter account, and sign up for our developer newsletter!