Home → Documentation → Configuration API → Swarms
Jump to

Swarms

Create and manage your swarms.

Create

  • URL: http://api.bugswarm.net/swarms
  • Method: POST
  • Headers:
    "x-bugswarmapikey: ${API_KEY}",
    "content-type: application/json"
  • Parameters (Required): None
  • Parameters (Optional): None

Create a swarm by passing a JSON object representing the swarm to create. After creation, you may add resources to the swarm. Additionally, users may specify any of their own resources to add to the swarm by default upon creation. This is configured in the JSON object that gets passed.

Body: The "name" and "description" fields are required. The "public" and "resources" fields are optional. The "public" field defaults to false if not specified. 
{
    "name": "My Other Swarm",
    "description": "My Other Swarm Description",
    "public": false,               
    "resources": [
        { "resource_id": "33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
          "resource_type": "consumer"
        }
    ]
}
Usage: Create a JSON file with the name create_swarm.json and matching the above format. Then execute: 
curl -X POST -d@create_swarm.json --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" --header "content-type: application/json" http://api.bugswarm.net/swarms
Returns: The created swarm and its configuration as a JSON object. The "resources" field will exist as an empty array if no resources are given upon creation. 
{
    "id": "92236421f64633430baa54fd9848e03aa2696111",
    "user_id": "username",
    "description": "My Other Swarm description",
    "name": "My Other Swarm"
    "created_at": "2011-08-29T20:17:08.676Z",
    "resources": [
        {
            "resource_id": "33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
            "resource_type": "consumer",
            "user_id": "username",
            "url": "http://api.bugswarm.net/resources/33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0"
        }                      
    ],
    "public": false
}

Update

  • URL: http://api.bugswarm.net/swarms/SWARM_ID
  • Method: PUT
  • Headers:
    "x-bugswarmapikey: ${API_KEY}",
    "content-type: application/json"
  • Parameters (Required): None
  • Parameters (Optional): None

Update a swarm by passing a JSON object containing the fields that the you wish to update.

Body: All fields are optional. 
{
    "name": "My Other Swarm updated",
    "description": "My Other Swarm description updated",
    "public": true
}
Usage: Create a JSON file with the name update_swarm.json and matching the above format. Then execute: 
curl -X PUT -d@update_swarm.json --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" --header "content-type: application/json" http://api.bugswarm.net/swarms/SWARM_ID
Returns: The updated swarm as a JSON object, including a "modified_at" field. 
{
    "description": "My Other Swarm description updated",
    "modified_at": "2011-10-10T01:08:54.688Z",
    "id": "92236421f64633430baa54fd9848e03aa2696111",
    "name": "My Other Swarm"
    "user_id": "username",
    "created_at": "2011-08-29T20:17:08.676Z",
    "resources": [
        {
            "resource_id": "33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
            "resource_type": "consumer",
            "swarm_id": "92236421f64633430baa54fd9848e03aa2696111",
            "user_id": "username",
            "url": "http://api.bugswarm.net/resources/33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
            "member_since": "2011-10-10T01:01:55.184Z"
        }                      
    ],
    "public": true
}

Destroy

  • URL: http://api.bugswarm.net/swarms/SWARM_ID
  • Method: DELETE
  • Headers: "x-bugswarmapikey: ${API_KEY}"
  • Parameters (Required): None
  • Parameters (Optional): None

Destroy a swarm. Destroying a swarm removes it completely from the user account. The method uses the unique swarm id specified in the URL to determine which swarm to destroy.

Usage: 
curl -X DELETE --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" http://api.bugswarm.net/swarms/SWARM_ID
Returns: HTTP Response Codes

List

  • URL: http://api.bugswarm.net/swarms
  • Method: GET
  • Headers:
    "x-bugswarmapikey: ${API_KEY}"
  • Parameters (Required): None
  • Parameters (Optional): Resource type

List all of the swarms owned by the user. Each listed swarm will also contain the resources that are a member of that swarm.

Usage: 
curl -X GET --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" http://api.bugswarm.net/swarms
Returns: A list of swarms as a JSON array. 
[
    {
        "id": "a16fb1d896817c58d4f4be9dea51e74b86519579",
        "user_id": "username",
        "description": "My Swarm description",
        "name": "My Swarm",
        "created_at": "2011-08-29T20:17:08.676Z",
        "resources": [
            {
                "resource_id": "33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
                "resource_type": "producer",
                "user_id": "username",
                "url": "http://api.bugswarm.net/resources/33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
                "member_since": "2011-10-10T01:01:55.184Z"
            },
            {
                "resource_id": "4735f4417f4fd2eb67ace9f2d2e7948e2d9f43f9",
                "resource_type": "both",
                "user_id": "username",
                "url": "http://api.bugswarm.net/resources/4735f4417f4fd2eb67ace9f2d2e7948e2d9f43f9",
                "member_since": "2011-10-10T01:01:55.184Z"
            }
        ],
        "public": true
    },
    {
        "id": "92236421f64633430baa54fd9848e03aa2696111",
        "user_id": "username",
        "description": "My Other Swarm description",
        "name": "My Other Swarm",
        "created_at": "2011-08-29T20:17:08.676Z",
        "resources": [
            {
                "resource_id": "33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
                "resource_type": "consumer",
                "user_id": "username",
                "url": "http://api.bugswarm.net/resources/33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
                "member_since": "2011-10-10T01:01:55.184Z"
            }                      
        ],
        "public": false
    }
]

Get Info

  • URL: http://api.bugswarm.net/swarms/SWARM_ID
  • Method: GET
  • Headers:
    "x-bugswarmapikey: ${API_KEY}"
  • Parameters (Required): None
  • Parameters (Optional): None

This method retrieves the information for a given swarm. The id of the swarm to retrieve the information from is given in the URL.

Usage: 
curl -X GET --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" http://api.bugswarm.net/swarms/SWARM_ID
Returns: A swarm as a JSON object. 
{
    "description": "My Other Swarm description",
    "id": "92236421f64633430baa54fd9848e03aa2696111",
    "modified_at": "2011-10-10T01:08:54.688Z",
    "name": "My Other Swarm"
    "user_id": "username",
    "created_at": "2011-08-29T20:17:08.676Z",
    "resources": [
        {
            "resource_id": "33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
            "resource_type": "consumer",
            "user_id": "username",
            "url": "http://api.bugswarm.net/resources/33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
            "member_since": "2011-10-10T01:01:55.184Z"
        }                      
    ],
    "public": true
}

Add Resource

  • URL: http://api.bugswarm.net/swarms/SWARM_ID/resources
  • Method: POST
  • Headers:
    "x-bugswarmapikey: ${API_KEY}"
    "content-type: application/json"
  • Parameters (Required): None
  • Parameters (Optional): None

Each swarm is owned by a given user and can be configured to contain resources. Swarms can contain the resources of many members. This method adds a resource to a given swarm. The method passes a JSON file containing the swarm-relevant information regarding the resource to add. The "type" field passed in the JSON refers to whether the resource will act as a producer or a consumer. This method can only be used to add your resources to a swarm that you own. To add another member's resource(s) to your swarm or to join another member's swarm with your resources, please see the invitations section of the API documentation.

Body: A JSON file containing the information of the resource to add that is relevant to the context of a swarm. 
{
    "resource_id": "33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
    "resource_type": "consumer"
}
Usage: Create a JSON file with the name add_resource.json and matching the above format. Then execute: 
curl -X POST -d@add_resource.json --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" --header "content-type: application/json" http://api.bugswarm.net/swarms/SWARM_ID/resources
Returns: HTTP Response Codes

Remove Resource

  • URL: http://api.bugswarm.net/swarms/SWARM_ID/resources
  • Method: DELETE
  • Headers:
    "x-bugswarmapikey: ${API_KEY}",
    "content-type: application/json"
  • Parameters (Required): None
  • Parameters (Optional): None

Each swarm is owned by a given user and can be configured to contain resources. Swarms can contain the resources of many members. This method removes a resource from a given swarm. The method passes a JSON file containing the information regarding the resource to remove. Removing a resource from a swarm does not remove it from the user account. To perform this action, use the Destroy method for user resources.

Body: A JSON file containing the information of the resource to remove from the swarm. 
{
    "resource_id": "33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
    "resource_type": "consumer"
}
Usage: Create a JSON file with the name remove_resource.json and matching the above format. Then execute: 
curl -X DELETE -d@remove_resource.json --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" --header "content-type: application/json" http://api.bugswarm.net/swarms/SWARM_ID/resources
Returns: HTTP Response Codes

List Resources

  • URL: http://api.bugswarm.net/swarms/SWARM_ID/resources
  • Method: GET
  • Headers:
    "x-bugswarmapikey: ${API_KEY}"
  • Parameters (Required): None
  • Parameters (Optional): Resource type

Users may list the resources that are members of a given swarm. The list will print each resource and its swarm-relevant information in JSON format.

Usage: 
curl -X GET --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" http://api.bugswarm.net/swarms/SWARM_ID/resources
curl -X GET --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" http://api.bugswarm.net/swarms/SWARM_ID/resources?type=producer
curl -X GET --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" http://api.bugswarm.net/swarms/SWARM_ID/resources?type=consumer
Returns: A list of resources as as JSON array. 
[
    {
        "resource_id": "33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
        "resource_type": "producer",
        "swarm_id": "a16fb1d896817c58d4f4be9dea51e74b86519579",
        "user_id": "username",
        "url": "http://api.dev.bugswarm.net/resources/33e675f7888c1d7f6f5da41bcccdff7b67f6c9a0",
        "member_since": "2011-10-10T01:01:55.184Z"
    },
    {
        "resource_id": "4735f4417f4fd2eb67ace9f2d2e7948e2d9f43f9",
        "resource_type": "consumer",
        "swarm_id": "a16fb1d896817c58d4f4be9dea51e74b86519579",
        "user_id": "username",
        "url": "http://api.dev.bugswarm.net/resources/4735f4417f4fd2eb67ace9f2d2e7948e2d9f43f9",
        "member_since": "2011-10-10T02:13:08.537Z"
    }
]