I created this mini tutorial to help coders quickly learn the Beagily basics. Beagily is a simple JSON data storage API.

  • Great for prototyping and rapid concept validation.
  • You define the structure of your data through the API as JSON Schema which supports.
  • You control who has access to data by assigning ownership to records.
  • Only pay for what you use pricing.

Prerequisites

  1. Create a Xilution account in our Test environment.
    1. Restricted access to Beagily is provided for FREE in our Test environment. See the Beagily product details page for pricing and restriction information.
  2. Activate Beagily through our Account Admin Portal in our Test environment.
    1. To activate Beagily (or any other Xilution product for that matter), log into the Account Admin Portal in Test and navigate to the Products page.
    2. Beagily may have been automatically activated when you created your account.
  3. Look up or create a Xilution Client.
    1. You'll need a client ID to request a Xilution Access Token.
    2. To see the clients associate with your Xilution account, log into the Account Admin Portal in Test and navigate to the Clients page.
  4. You'll need a way to interact with the API. We recommend the Insomnia REST client, but you could use any similar app. You could also simply use cURL as well.
Note: At the time of this writing our Test and Prod accounts are not synchronized. So, if you choose to use Beagily in our Prod environment, you'll need to repeat these step in Prod.

Authentication

Beagily (along with all other Xilution APIs) uses the OAuth 2 authentication. To acquire a Xilution Access Token...

POST: https://test.authentication.core.api.xilution.com/oauth/token

grant_type=password&username={your-username}&password={your-password}&client_id={your-client-id}&scope=read%20
write

Response: The response will include a property named access_token. This is your Xilution Access Token. It is a bearer token. You will included this as a request header called Authentication with each subsequent request mentioned in this mini-tutorial. The value of the header will take the form of: Bearer {your-xilution-access-token}.
Note: The format of the this Post body is x-www-form-urlencoded and should be URL encoded.

Create a Type

Beagily uses schema defined by you to validate things that you POST and PUT to the API. You register your schema with Beagily like this.

PUT: https://test.beagily.basics.api.xilution.com/types/pet

{
  "$schema": "http://json-schema.org/schema#",
  "title": "Pet Schema",
  "type": "object",
  "properties": {
    "@type": {
      "enum": [
        "pet"
      ],
      "type": "string"
    },
    "owningUserId": {
      "type": "string"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "@type",
    "owningUserId",
    "name"
  ]
}

Remember: You need to include the Authorization header with this request and all the following requests.
Note: @type and owningUserId are required thing properties in Beagily. The type name and the enum are both singular.

If you want to see your pet type you can...

GET: https://test.beagily.basics.api.xilution.com/types/pet

Create a Pet

POST: https://test.beagily.basics.api.xilution.com/things?type=pet

{
  "@type": "pet",
  "name": "Muffy",
  "owningUserId": "{your-user-id}"
}

Response: The response headers include a Location property that includes the identifier of the new pet.
Note: As before, the type name is singular.

Update the Pet

PUT: https://test.beagily.basics.api.xilution.com/things?type=pet

{
  "@type": "pet",
  "id": "{the-pet-id-found-in-the-create-response-location-header}",
  "name": "Dusty",
  "owningUserId": "{your-user-id}"
}

Note: As before, the type name is singular.

Get the Pet

GET: https://test.beagily.basics.api.xilution.com/things/{the-pet-id-found-in-the-create-response-location-header}?type=pet

Note: As before, the type name is singular.

Search for the Pet

GET: https://test.beagily.basics.api.xilution.com/things?page-size=10&page-number=0&type=pet

Response: The response will be the pet that you posted earlier including the ID and some other meta-data.
Note: Pet is singular again and the page index is zero based.

If you want to narrow the search, add a filter using the q query parameter...

GET: https://test.beagily.basics.api.xilution.com/things?page-size=10&page-number=0&type=pet&q=name:Dusty

Other Resources

Wrap Up

Hope this mini-tutorial inspires you to give Beagily a try and helps you quickly get up to speed with the Beagily basics. If you find the instructions need more context send us an email at support@xilution.com and we'll make the needed changes. Happy coding!