The Atomic API is a critical service for any app dealing with NFTs on the WAX Blockchain. Unfortunately, the documentation for the API is not the best and many developers fall into the same traps when working with the API.

Swagger Docs

The first resource you need to know about is the Swagger docs. This contains all the endpoints and parameters they accept. If you're already familiar with Swagger then this may be all you need. But be sure to read on, and we will highlight some of the common mistakes made so you can avoid them.

The Swagger docs are available on most endpoints via the /docs/ path.
https://wax.api.atomicassets.io/docs/

Endpoints

In the WAX ecosystem, WAX Guilds (block producers) provide many public Atomic API nodes, so your app shouldn't need to rely on just one. It is good practice to implement redundancy, fallbacks, and even let your users choose which node they want to use.

You can find a full list of active endpoints here:
https://validate.eosnation.io/wax/reports/endpoints.html#atomic_https

Packages

You don't have to make raw API requests with fetch or axios yourself, there are a few packages that provide API wrappers to help you out.

The newest package on the block is part of the Wharf SDK. It is a JavaScript package that provides fully typed API requests and responses.
https://www.npmjs.com/package/@wharfkit/atomicassets

There are also two older packages provided by the Atomic team for atomicassets and atomicmarket respectively.

https://www.npmjs.com/package/atomicassets
https://www.npmjs.com/package/atomicmarket

Common Mistakes

Too many API calls

One of the most common mistakes seen with apps using the Atomic API is redundant API calls. When a page needs to load data for multiple templates or assets, sometimes developers will make a separate API request for each. This is bad. It can cause your app to get blocked from the API node you are using and your users to get rate limited.

The API allows for requesting multiple items in a single request with the use of the ids parameter which accepts a comma-separated list of IDs.

https://wax.api.atomicassets.io/atomicassets/v1/templates?ids=104209,104208,104207

So build your app to take advantage of this and not spam API requests unnecessarily.

Pagination

The Atomic API has pagination built in, the default limit is 100 and the maximum limit is 1000. When requesting templates, assets, or other endpoints, it makes sense to do as few requests as possible. So take advantage of the limit and page parameters in your API requests.

POST

The Atomic API allows you to make both GET and POST requests. When making a GET request, if a query string gets too long an error will be thrown, but you can make a POST request instead. If you use the Atomic atomicassets and atomicmarket npm packages it will do this automatically.

However, there is a bug in the Atomic API server that will ignore any POST request parameters sent as numbers. So if you are using those Atomic npm packages or making manual API requests, be sure to cast any limit and page parameters as string.

The Whaf atomicassets package always makes POST requests and accounts for these bugs in the Atomic API.

I hope this article was helpful, if you have any questions there are plenty of helpful people, including myself, in the WAX Developers Telegram and on the official WAX Discord in the #get-dev-help channel.

Working with the Atomic API