Shotgun API

Table of Contents

• Introduction
• Installation
• Notes
• API Details
  • Connecting to Shotgun
  • Finding entities
  • Creating, modifying, deleting, and reviving entities
  • Batch operations
  • Meta-Schema queries
  • Uploading and downloading files
  • Using ShotgunRequest Objects
• TODOs
• Dependencies
• Links

Introduction

This is an objective c port of the python shotgun api.

For complete documentation of how the Python Shotgun API works along with tutorials, examples, and other details see:
https://github.com/shotgunsoftware/python-api/wiki

Installation

• Start by downloading the code from https://github.com/shotgunsoftware/objc-api
• Copy the files in Classes directory into your project.
• Copy the dependencies into your project.
  
  All the dependencies are included as git submodules in the Dependencies directory.
  You can either download the dependencies yourself or (if you cloned the project via
  git rather than downloading the tarball) run 'git submodule init' followed by
  'git submodule update' to download the projects at the revision as of the writing of
  this library.
  
  
  • json-framework - Copy the files in Classes into your project.
  • asi-http-request (See the official docs for more in depth instructions).
    • Copy the files in Classes into your project (just the files, the directories are not needed)
    • Copy the files in External/Reachability into your project.
    • Link against CFNetwork, SystemConfiguration, MobileCoreServices, CoreGraphics and zlib

Note, it is also possible to compile this as a library and link that into your project as a sub-project. This is cleaner, but more difficult to setup. See the example project under Examples to see what this setup would look like.

• To get the example project or unit tests to run you need to copy the Config.plist.template file to Config.plist and update the values for your shotgun server.

Notes

• All Date objects are assumed to be in UTC (This is the default NSDate behavior).
• The default NSOperationQueue for ShotgunRequests will run up to 4 requests concurrently.

API Details

Connecting to Shotgun

  NSString *url = @"http://mysite.shotgunsoftware.com";
  NSString *script = @"example_script";
  NSString *key = @"abcdefghijklmnopqrstuvwxyz";
  Shotgun *shotgun = [[[Shotgun alloc] initWithUrl:url scriptName:script andKey:key] autorelease];

Finding entities

  ShotgunRequest *request = 
    [shotgun findEntitiesOfType:@"Version"
                    withFilters:@"[[\"code\", \"starts_with\", \"100\"]]"
                      andFields:@"[\"code\", \"image\"]"];
  [request startSynchronous];
  NSArray *results = [request response];

Creating, modifying, deleting, and reviving entities

  ShotgunEntity *shot = [[shotgun createEntityOfType:@"Shot"
                withData:@"{\"code\": \"s10\", \"description\": \"Shot 10\"}"] startSynchronous];

  ShotgunRequest *request = [shotgun updateEntityOfType:@"Shot"
                                            withId:[NSNumber numberWithInt:23]
                                          withData:@"{\"description\": \"Shot 20 - More Info\"}"];
  ShotgunEntity *shot = [request startSynchronous];

  ShotgunRequest *request = [shotgun deleteEntityOfType:@"Shot" withId:[NSNumber numberWithInt:23]];
  [request startSynchronous];
  BOOL success = [[request response] boolValue];

  ShotgunRequest *request = [shotgun reviveEntityOfType:@"Shot" withId:[NSNumber numberWithInt:23]];
  [request startSynchronous];
  BOOL success = [[request response] boolValue];

Batch operations

  ShotgunRequest *request = [shotgun batch:@"[" \
      "{                                 " \
      " \"request_type\": \"create\",    " \
      " \"entity_type\":  \"Shot\",      " \
      " \"data\": {                      " \
      "     \"code\": \"s10\",           " \
      "     \"description\": \"Shot 10\" " \
      "   }                              " \
      "},                                " \
      "{\"request_type\": \"delete\", \"entity_type\": \"Shot\", \"entity_id\": 23}" \
    ]"];
  [request startSynchronous];
  NSArray *results = [request response];

Meta-Schema queries

  ShotgunRequest *request = [shotgun schemaEntityRead];
  [request startSynchronous];
  NSDictionary *schemaInfo = [request response];

  ShotgunRequest *request = [shotgun schemaRead];
  [request startSynchronous];
  NSDictionary *schema = [request response];

  ShotgunRequest *request = [shotgun schemaFieldReadForEntityOfType:@"Shot" forField:@"sg_status_list"];
  [request startSynchronous];
  NSDictionary *entitySchema = [request response];

Uploading and downloading files

  NSNumber *attachmentId = [shotgun uploadThumbnailForEntityOfType:@"Shot"
                                         withId:[NSNumber numberWithInt:23]
                                       fromPath:@"/path/to/the/file.jpg"];

  NSData *imageData = downloadAttachmentWithId:[NSNumber numberWithInt:201];

  ShotgunEntity *entity = [[shotgun findEntityOfType:@"Version"
                                         withFilters:filters
                                           andFields:fields] startSynchronous];
  [shotgun thumbnailForEntity:entity withBlock:^(UIImage *thumbnail) {
        NSString *aURL = [shot objectForKey:@"image"];
        NSLog(@"URL: %@ is %dx%d", aURL, thumbnail.size.width, thumbnail.size.height);
  }];

Using ShotgunRequest Objects

ShotgunRequests can be run either synchronously or asynchronously.

To run a request syncronously simply call startSyncronously:

  [request startSyncronous];

The request will block the current thread until it is finished and its response is ready.

To run a request asynchronously call startAsynchronous:

  [request startAsynchronous];

Control will return to the current thread right away. To process the response to the request, register callback blocks with request before starting it:

  [request setCompletionBlock:^{
     id response = [request response];
     // Do Stuff with the response
  }];

The currently supported callbacks are:

• startedBlock - Called when the request is started.
• completionBlock - Called when the request has finished.
• failedBlock - Called when the request failed.

The postProcessBlock is used internally to the API and should not be overridden.

ShotgunEntities

Any dictionary returned by a create, update, or find call is a ShotgunEntity object which adds some shotgun specific logic on top of an NSMutableDictionary.

  ShotgunEntity *entity = [request response];
  NSLog(@"My entity type is %@ , my entity id is %@", entity.entityType, entity.entityId);

Dates

All dates handled by the API are UTC dates (the default timezone for NSDate objects).
date_time fields in shotgun are returned as ShotgunDateTime objects. date fields in shotgun are returned as strings ("YYYY-MM-DD") like in the Python API.
When passing dates into the API, NSDate objects are not allowed, you must use ShotgunDate or ShotgunDateTime objects.

Dependencies

• ASIHTTPRequest: http://allseeing-i.com/ASIHTTPRequest/
• SBJson: http://stig.github.com/json-framework/
• GHUnit (only needed to run the unit tests): https://github.com/gabriel/gh-unit

Links

• Python API: https://github.com/shotgunsoftware/python-api
• Mailing List: https://groups.google.com/group/shotgun-objc-api
• Issues: https://github.com/shotgunsoftware/objc-api/issues

TODOs

• Switch from Exceptions to NSErrors
• Add support for responding to events via delegate SELs
• Add support for asychronous image field resolution
• Better API around paging
• Finish documentation
• Round out unit tets. Use OCMock.
• Switch to a decent logging system
• Other inline TODOs

Rob Blau <rblau@laika.com>