Installation is straightforward. Since we use fetch underneath the
hood, we recommend installing alongside a fetch polyfill.
If using yarn:
If using npm:
Now import it:
…or, if you’re avoiding JS modules, spraypaint will be available as a global in
Spraypaint supports Typescript versions >= 2.8.
By default you will need a ! after each attribute and relationship:
This is due to Strict Class Initialization. For the purposes of Spraypaint, we don’t need this. Remove the need for
! (as the rest of these guides do) by setting
Connecting to the API
Just like ActiveRecord, our models will inherit from a base class that
holds connection information (ApplicationRecord, or
ActiveRecord::Base in Rails < 5):
All URLs follow the following pattern:
baseUrl + apiNamespace + jsonapiType
As you can see above, typically baseUrl and apiNamespace are set on
a top-level ApplicationRecord (though any subclass can override).
jsonapiType, however, is set per-model:
With the above configuration, all Person endpoints will begin
TIP: Avoid CORS and use relative paths by simply setting baseUrl to
TIP: You can always use the endpoint option to override this pattern
and set the endpoint manually.
Setting Application Name
It can be helpful to send the name of your client application in request
headers. With this information, servers can keep track of which clients
are hitting which APIs.
To do this:
ActiveRecord automatically sets attributes by introspecting database
columns. We could do the same - swagger.json is our schema - but tend
to agree with those who feel this aspect of ActiveRecord is a bit too
“magical”. In addition, explicitly defining our attributes can be used
to track which applications are using which attributes of the API.
Though this is configurable, by default we expect the API to be
under_scored and attributes to be camelCased.
Attributes can be marked read-only, so they are never sent to the server
on a write request:
Just like ActiveRecord, there are HasMany, BelongsTo, and
By default, we expect the relationship name to correspond to a
pluralized jsonapiType on a separate Model. If your models don’t
use this convention, feel free to supply it explicitly: