In order to assist the building of your own tools and the extension of our platform, we are introducing the second major iteration of our API with support for geographic distribution, simpler API calls, OAuth 2.0 and overhauled API docs.
With this release, we aimed for making the API much more accessible, consistent and fault-tolerant. Read on to understand how we accomplished this and what else is in store for your team.
Previously, all requests to the API were handled exclusively by our SFO region (California). With the new release, the API has additionally been enabled in our BRU (Belgium) region.
Depending on geographic origin, requests to api.zeit.co are now being routed to the closest data center automatically. To make this possible, we have been hard at work to ensure all deployment metadata has been geographically replicated.
If a region is unavailable, we can now fail-over API calls to another region – automatically and reliably, with zero interruption.
As of version 2.0, our API provides public endpoints for all interactions that are performed by ZEIT's official clients (like Now Desktop, Now CLI and the dashboard), allowing you to build clients and applications just as powerful as ours.
Further, most actions can be performed with a single API call. For example, this is how you purchase a new domain:
▲ ~/my-app $
In place of the token, you need to generate your own
Once you have run that command (which you can also find here for copying and pasting), the domain will be available for use inside the account from which the token was generated.
We have also overhauled our deployment API calls.
Previously, we had two separate endpoints for deployments: one for inlining the source code into the request, and another for using our streaming API. They are now combined, requiring a single API call to create your deployment:
As you can see, both ways of uploading files are included in this example: inlining (package.json) and streaming (index.js).
For the latter to work, you must additionally stream the index.js file to the upload endpoint. The endpoint for creating the deployment will let you know which files haven't yet been uploaded each time it is called.
The sha field contains a SHA1 checksum and can be generated like so:
This is all you need to know for creating a deployment. Read more here.
If you are building an application or service that would benefit by connecting to our platform, you can now request an access token by forwarding the user to our new OAuth2 endpoint:
Assuming that you have passed all required parameters and the user has completed the sign-in flow (shown below), you will then be able to communicate with the new API on behalf of the user - CodeSandbox being a great example.
In order to make it easier to develop applications that take advantage of our API, we have created new API docs filled with details outlining the usage of each endpoint.
Previously, we only provided documentation for our "Instant API", which only exposed a limited range of functionality. Now that there's a single API for every operation on the Now platform, every single method we use in our own official clients has been documented:
In addition to providing usage information for each API endpoint, we made sure to carefully explain each potential error and what has changed between each subsequent version of the API.
An example curl request is also included alongside each endpoint:
We are working very hard to make sure our documentation always reflects the current state of all of our products. However, if you encounter any missing or incorrect information, we would be happy to accept a pull request.
Over 18 months ago, we merged a package into our ecosystem which has since acted as the officially recommended way of communicating with our API.
As of today, now-client will be deprecated.
Instead of maintaining code that should not be necessary in most use cases, we are focusing on simplifying our API endpoints even further – ensuring that such an abstraction never stands in way of communicating with our API.
We are committed to making all of our APIs public and to iterate on them frequently. All suggestions and requests are more than welcome.