Tutorial: Create a collection

What you'll learn

Through this tutorial, you'll learn to:

  • Create a collection.
  • Add entities to the collection.
  • Update entities.
  • List all entities in the collection.

API BaaS includes a NoSQL data store built on the Apache Usergrid project. In addition to an Admin Portal for ease of data management, API BaaS also provides SDKs for working with the data store in your client apps.

In this tutorial, for simplicity, you'll learn how to create and update a data collection in API BaaS using the Admin Portal and cURL.

What you'll need

  • An Apigee Edge account. If you don't have one yet, you can sign up with the directions at Creating an Apigee Edge account.
  • cURL installed on your machine to make API calls from the command line.

Create a collection of books

A collection in API BaaS is a grouping of similar data. In this section, you'll create a collection called books that will contain individual book titles and data.

About the Sandbox

A Sandbox application is automatically created for each organization in API BaaS. For ease-of-demo convenience, API calls to the Sandbox app don't require a key or credentials. For more information, see Using a Sandbox Application.

  1. Go to the API BaaS Admin Portal:
    (If you're redirected to the accounts dashboard, click API BaaS.)
  2. Select the Edge organization you want to work in, and select the Sandbox application.
  3. Click Data in the left nav bar, and click the "+" icon in the "Collections" pane to add a new collection.
  4. In the "Create new collection" window:
    In this field do this
    Collection Name

    Enter: book

    API BaaS will automatically add an "s" to the collection name, making it "books".

    Create a new entity for your collection Leave as is. This will create a first entity in the collection called "test".
  5. Click Create.
    The collection appears in the list. Notice that API BaaS added an "s" to the collection, making it /books.
  6. Click the /books collection.
    Notice the default first entity in the collection called "test" with its auto-generated data expanded.

Congratulations! You've created a collection. Now you can start adding individual books to it.

Add books to the collection

Now that you have a collection, you can start adding books to it.

Your client apps

This tutorial shows basic CRUD operations on collections using the Admin Portal and cURL. In actual practice, your app code will perform CRUD operations on the data. API BaaS provides different language SDKs for manipulating collections and entities.

  1. With the /books collection selected:
    In this field do this
    Verb drop-down

    Select: POST

    Make sure /books is in the text box next to it.

    JSON Body


      "name": "The Grapes of Wrath"
  2. Click Validate JSON to make sure your JSON is well formed.
  3. Click Send.
    The new book, "The Grapes of Wrath", appears in the entity list.
  4. Add another book called Of Mice and Men to the /books collection.
    If you click the Hide Details link next to the new book, you can see all the books in your collection, including the "test" entity.

Update books in the collection

You've got two books in your collection, and it so happens that they're written by the same author. To add an author, you could use the Admin Portal to do a PUT on each book to add { "author" : "John Steinbeck" }.

But we'll use a cURL command instead, which can add the author to both books with one call.

  1. First, delete the "test" entity. In the Admin Portal, with the /books collection selected, select the check box next to "test" and click Delete Entity(s).
  2. In a terminal window, run the following command, replacing <host_name> with the Apigee BaaS base URL and {org_name} with the name of your organization.
    curl -X PUT https://<host_name>/{org_name}/<org_name>sandbox/books/?ql= -d '{ "author" : "John Steinbeck" }'    
    A successful call returns JSON like this:
      "action" : "put",
      "application" : "2f22ed80-6af8-11e5-a59a-1b831d76c60c",
      "params" : {
        "ql" : [ "" ]
      "path" : "/books",
      "uri" : "https://<host_name>/docfood/sandbox/books",
      "entities" : [ {
        "uuid" : "6ed3c75a-bb0d-11e5-bffa-9bbdbd34b62a",
        "type" : "book",
        "name" : "The Grapes of Wrath",
        "created" : 1452810207301,
        "modified" : 1452810771010,
        "author" : "John Steinbeck"
      }, {
        "uuid" : "733d8a1a-bb0d-11e5-825f-61ecf4b380dd",
        "type" : "book",
        "name" : "Of Mice and Men",
        "created" : 1452810214705,
        "modified" : 1452810771027,
        "author" : "John Steinbeck"
      } ],
      "timestamp" : 1452810770997,
      "duration" : 44,
      "organization" : "docfood",
      "applicationName" : "sandbox"
  3. In the Admin Portal, click the /books collection to refresh it, then click View Details next to one of the entities to see the new author data.

List entities in the collection

Finally, run the following cURL command to list all the entities in your collection. Replace <host_name> with the Apigee BaaS base URL and {org_name} with the name of your organization.

In your client apps, listing entities in a collection is a common function. Your code will get the response (entity list), and you can parse, paginate, and perform any other desired logic on the list for your end users.

curl -X GET https://<host_name>/{org_name}/<org_name>sandbox/books

You should get a similar JSON response to what you got when adding the author to your books.