Common Conventions

Property Identifiers

When getting or pushing data the request needs to identify which data you would like to get, or which data you are trying to push. In order to identify the data, Slatwall has a convention knows as "Property Identifiers" and you will see this term referenced often througout the docs.

Any time we are getting or pushing data, there is always a contextual object or entity that we are talking about. Property Identifiers are simply a string that represents a "path" to the data you want.  For example if you look at an API request for an Account.

curl -X GET \
--header "Content-Type: application/json" \
--data '{
"authToken" : "205c1fd430fb4588bf5a5b82a03fe1af",
"accountID" : "8c06bbba048f4ce9ba36e23d10d38f13"
}' \
"https://www.myslatwallinstance.com/api/Account"

 

Under this context all property identifiers that are defined are done so contextually from the base Account entity because that is the API Endpoint that we are hitting.

First there are some simple property identifiers that we could use when talking about this account:

firstName,
lastName,
company

 

If you look at the reference docs for the Account entity you will see that these are all various property names of properties that exist on the Account entity.

What if we wanted to drill into data in an object that is related to the Account object, but not the account object itself? Well, we can link together properties to drill into related objects. Here are some examples of identifying data that is related to the Account object via a chain of many-to-one relationships.

primaryEmailAddress.emailAddress,
primaryAccountAddress.address.countryCode,
accountCreatedSite.siteName

 

When it comes to "getting" data about a one-to-many property it works the same way, the only difference being that the propertyNames will typically be plural.  For example, lets say that this account has multiple email addresses, and I want to get the data back from all.

accountEmailAddresses.emailAddress

 

The only difference is when we are pushing data up to the Slatwall server. In that case we want to use array notation so that we can create "groups" of information. Lets say that I want to add 2 new email addresses, and update an existing one.  My data would look something like this:

accountEmailAddresses[1].accountEmailAddressID : '406c1be430fb4777bf5a5b82a03fe1af',
accountEmailAddresses[1].emailAddress : 'john@doe.com',
accountEmailAddresses[2].accountEmailAddressID : '',
accountEmailAddresses[2].emailAddress : 'john@gmail.com',
accountEmailAddresses[3].accountEmailAddressID : '',
accountEmailAddresses[3].emailAddress : 'john@company.com'

You'll notice that the first record I've defined an existing ID for the object that I'm updating. However the other two have an ID field which is blank which tells Slatwall to create a new entity for that record.

You will run into Property Indentifiers in almost any code example, so it's important to have a really good understanding of exactly how they work.

Questions & Comments