http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/sdks/ios-new.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/sdks/ios-new.txt b/content/docs/_sources/sdks/ios-new.txt new file mode 100644 index 0000000..0f5b3fe --- /dev/null +++ b/content/docs/_sources/sdks/ios-new.txt @@ -0,0 +1,982 @@ +# Usergrid iOS SDK + +## Getting Started + +### Installing the SDK +### Building from Source + +# Usergrid SDK Reference with Examples + +The 66 topics listed below are each documented in the Usergrid documentation and +for each the docs provide an API reference and example for each of these clients: +curl, iOS, Android, JavaScript, Ruby and Node.js. + +## Working with Collections + +### 1. Creating collections + +SDK Method + + (ApigeeClientResponse *)apiRequest: (NSString *)url operation:(NSString *)op data:(NSString *)opData + +Parameters + +Parameter Description +--------- ----------- +url A fully-formed url in the following format: https://api.usergrid.com/<org>/<app>/<collection> +op The HTTP method - in this case, 'POST' +opData No data is being sent, so the value is nil + +Example Request/Response + +Request: + + -(NSString*)createCollection { + + NSString *url = @"https://api.usergrid.com/your-org/your-app/items";; + NSString *op = @"POST"; + NSString *opData = nil; + + //we recommend you call ApigeeClient from your AppDelegate. + //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios + //create an instance of AppDelegate + AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate]; + + //call createEntity to initiate the API call + ApigeeClientResponse *response = [appDelegate.dataClient apiRequest: url operation: op data: opData]; + + @try { + //success + } + @catch (NSException * e) { + //fail + } + + } + +Response: + + { + "action" : "post", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items";, + "entities" : [ ], + "timestamp" : 1378857079220, + "duration" : 31, + "organization" : "your-org", + "applicationName" : "your-app" + } + +### 2. Retrieving collections + +SDK Method + + (ApigeeCollection*)getCollection:(NSString*)type + +Parameters + +Parameter Description +--------- ----------- +type The entity type associated with the collection to be retrieved + +Example Request/Response + +Request: + + -(NSString*)getCollection { + + //specify the entity type that corresponds to the collection to be retrieved + NSString *type = @"item"; + + //we recommend you call ApigeeClient from your AppDelegate. + //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios + + //create an instance of AppDelegate + AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate]; + + //Call getCollection: to initiate the API GET request + ApigeeCollection *collection = [appDelegate.dataClient getCollection:@"book"]; + } + +Response: + + { + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items";, + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + }, { + "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055", + "type" : "item", + "name" : "bread", + "created" : 1378423379867, + "modified" : 1378423379867, + "metadata" : { + "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055" + }, + "name" : "bread", + "price" : "2.50" + } ], + "timestamp" : 1378426821261, + "duration" : 35, + "organization" : "your-org", + "applicationName" : "your-app", + "count" : 2 + } + +### 3. Updating collections + +SDK Method +(ApigeeClientResponse *)apiRequest: (NSString *)url operation:(NSString *)op data:(NSString *)opData +Properties +Parameter Description +url A fully-formed request url in the following format: +https://api.usergrid.com/<org>/<app>/<collection>/?ql= +Note that you must include an empty '?ql=' query string at the end of the URL + +op The HTTP method - in this case, 'PUT' +opData A JSON-formatted string that contains the entity properties to be updated +Example Request/Response +Show Code +Request: +-(NSString*)updateCollection { + + NSString *url = @"https://api.usergrid.com/your-org/your-app/items/?ql";; + NSString *op = @"PUT"; + NSString *opData = @"{\"availability\":\"in-stock\"}"; //we escape the quotes + + //we recommend you call ApigeeClient from your AppDelegate. + //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios + //create an instance of AppDelegate + AppDelegate *appDelegate = (AppDelegate *)[[UIApplication sharedApplication] delegate]; + + //call apiRequest to initiate the API call + ApigeeClientResponse *response = [appDelegate.dataClient apiRequest: url operation: op data: opData]; + + @try { + //success + } + @catch (NSException * e) { + //fail + } + +} + +Response: +{ + "action" : "put", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { + "ql" : [ "" ] + }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items";, + "entities" : [ { + "uuid" : "31847b9a-1a62-11e3-be04-8d05e96f700d", + "type" : "item", + "name" : "milk", + "price" : "3.25", + "availability" : "in-stock" + "created" : 1378849479113, + "modified" : 1378849567301, + "name" : "milk", + }, { + "uuid" : "3192ac6a-1a62-11e3-a24f-496ca1d42ce7", + "type" : "item", + "name" : "bread", + "price" : "4.00", + "availability" : "in-stock" + "created" : 1378849479206, + "modified" : 1378849567351, + "name" : "bread", + } ], + "timestamp" : 1378849567280, + "duration" : 207, + "organization" : "your-org", + "applicationName" : "your-app" +} + +### 4. Deleting collections + +SDK Method +(ApigeeClientResponse *)apiRequest: (NSString *)url operation:(NSString *)op data:(NSString *)opData +Properties +Parameter Description +url A fully-formed url in the following format: +https://api.usergrid.com/<org>/<app>/<collection>/?ql= +Note that you must include an empty '?ql=' query string at the end of the URL + +op The HTTP method - in this case, 'DELETE' +opData No data is being sent, so the value is nil +Example Request/Response +The following example will delete the first 5 entities in a collection. + +Show Code +Request: +-(NSString*)deleteCollection { + + NSString *url = @"https://api.usergrid.com/your-org/your-app/items/?ql='limit=5'"; + NSString *op = @"DELETE"; + NSString *opData = nil; + + //we recommend you call ApigeeClient from your AppDelegate. + //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios + //create an instance of AppDelegate + AppDelegate *appDelegate = (AppDelegate *)[[UIApplication sharedApplication] delegate]; + + //call createEntity to initiate the API call + ApigeeClientResponse *response = [appDelegate.dataClient apiRequest: url operation: op data: opData]; + + @try { + //success + } + @catch (NSException * e) { + //fail + } + +} + +Response: +{ + "action" : "delete", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { + "ql" : [ "" ] + }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items";, + "entities" : [ { + "uuid" : "53fe3700-0abe-11e3-b1f7-1bd100b8059e", + "type" : "item", + "name" : "milk", + "price" : "3.25", + "created" : 1377129832047, + "modified" : 1377129832047, + "metadata" : { + "path" : "/items/53fe3700-0abe-11e3-b1f7-1bd100b8059e" + }, + "name" : "milk" + }, { + "uuid" : "5ae1fa7a-0abe-11e3-89ab-6be0003c809b", + "type" : "item", + "name" : "bread", + "price" : "4.00", + "created" : 1377129843607, + "modified" : 1377129843607, + "metadata" : { + "path" : "/items/5ae1fa7a-0abe-11e3-89ab-6be0003c809b" + }, + "name" : "bread" + } ], + "timestamp" : 1378848117272, + "duration" : 12275, + "organization" : "your-org", + "applicationName" : "your-app" +} + +## Working with Entities + +### 5. Creating a custom entity + +SDK Method +(ApigeeClientResponse *)createEntity:(NSDictionary *)newEntity +Parameters +Parameter Description +newEntity NSDictionary object that contains the entity properties +Example Request/Response +Show Code +Request: +-(NSString*)newEntity { + + //create an entity object + NSMutableDictionary *entity = [[NSMutableDictionary alloc] init ]; + + //Set entity properties + [entity setObject:@"item" forKey:@"type"]; //Required. New entity type to create + [entity setObject:@"milk" forKey:@"name"]; + [entity setObject:@"3.25" forKey:@"price"]; + + //we recommend you call ApigeeClient from your AppDelegate. + //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios + //create an instance of AppDelegate + AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate]; + + //call createEntity to initiate the API call + ApigeeClientResponse *response = [appDelegate.dataClient createEntity:entity]; + + @try { + //success + } + @catch (NSException * e) { + //fail + } + +} + +Response: + { + "action" : "post", + "application" : "4a1edb70-d7a8-11e2-9ce3-f315e5aa568a", + "params" : { }, + "path" : "/items", "uri" : "http://api.usergrid.com/my-org/my-app/items";, + "entities" : [ { + "uuid" : "83e9b7ea-e8f5-11e2-84df-e94123890c7a", + "type" : "item", + "name" : "milk", + "created" : 1373415195230, + "modified" : 1373415195230, + "metadata" : { + + "path" : "/items/83e9b7ea-e8f5-11e2-84df-e94123890c7a" + }, + "name" : "milk", + "price" : "3.25" + } ], + "timestamp" : 1373415195225, + "duration" : 635, + "organization" : "my-org", + "applicationName" : "my-app" + } + + +### 6. Creating multiple custom entities + +Request Syntax +curl -X POST https://api.usergrid.com/<org>/<app>/<entity_type>/ -d '[{<entity>}, {<entity>}, ...]' +Parameters +Parameter Description +org Organization UUID or name +app Application UUID or name +entity_type Custom entity type to create. API Services will create a corresponding collection if one does not already exist. To add an entity to an existing collections, use the collection name or colleciton UUID in place of the entity type. +entity Comma-separated list of entity objects to create. Each object should be formatted as a comma-separated list of entity properties, formatted as key-value pairs in the format <property>:<value> +Example Request/Response +Show Code +Request: +curl -X POST "https://api.usergrid.com/your-org/your-app/item"; -d '[{"name":"milk", "price":"3.25"}, {"name":"bread", "price":"2.50"}]' +Response: +{ + "action" : "post", + "application" : "f34f4222-a166-11e2-a7f7-02e9sjwsf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items";, + "entities" : [ { + "uuid" : "f3a8061a-ef0b-11e2-9e92-5f4a65c16193", + "type" : "item", + "name" : "milk", + "price" : "3.25", + "created" : 1374084538609, + "modified" : 1374084538609, + "metadata" : { + "path" : "/multis/f3a8061a-ef0b-11e2-9e92-5f4a65c16193" + }, + "name" : "milk" + }, { + "uuid" : "f3be262a-ef0b-11e2-a51b-6715d5ef47a6", + "type" : "item", + "name" : "bread", + "price" : "2.50", + "created" : 1374084538754, + "modified" : 1374084538754, + "metadata" : { + "path" : "/items/f3be262a-ef0b-11e2-a51b-6715d5ef47a6" + }, + "name" : "bread" + } ], + "timestamp" : 1374084538584, + "duration" : 388, + "organization" : "your-org", + "applicationName" : "your-app" +} + +### 7. Creating an entity with sub-properties + +SDK Method +(ApigeeClientResponse *)createEntity:(NSDictionary *)newEntity +Parameters +Parameter Description +newEntity NSMutableDictionary object that contains the entity properties +Example Request/Response +Show Code +Request: +-(NSString*)newEntity { + + //Initialize an object for the new entity to be created + NSMutableDictionary *entity = [ [NSMutableDictionary alloc] init ]; + + //Initialize an object for each nested variety object + NSMutableDictionary *variety_1 = [ [NSMutableDictionary alloc] init ]; + NSMutableDictionary *variety_2 = [ [NSMutableDictionary alloc] init ]; + NSMutableDictionary *variety_3 = [ [NSMutableDictionary alloc] init ]; + + //Initialize an array to hold the nested variety objects + NSMutableArray *variety_list = [ [NSMutableArray alloc] init]; + + [variety_1 setObject:@"1%" forKey:@"name"]; + [variety_1 setObject:@"3.25" forKey:@"price"]; + [variety_1 setObject:@"0393847575533445" forKey:@"sku"]; + + [variety_2 setObject:@"whole" forKey:@"name"]; + [variety_2 setObject:@"3.85" forKey:@"price"]; + [variety_2 setObject:@"0393394956788445" forKey:@"sku"]; + + [variety_3 setObject:@"skim" forKey:@"name"]; + [variety_3 setObject:@"4.00" forKey:@"price"]; + [variety_3 setObject:@"0390299933488445" forKey:@"sku"]; + + //Add the variety objects to the array + [variety_list addObject:variety_1]; + [variety_list addObject:variety_2]; + [variety_list addObject:variety_3]; + + //Set the item entity properties + [entity setObject:@"item" forKey:@"type"]; //Required. New entity type to create + [entity setObject:@"milk" forKey:@"name"]; + + //Set the variety_list array as the value of the 'varieties' property + [entity setObject:variety_list forKey:@"varieties"]; + + //we recommend you call ApigeeClient from your AppDelegate. + //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios + //create an instance of AppDelegate + AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate]; + + //call createEntity to initiate the API call + ApigeeClientResponse *response = [appDelegate.dataClient createEntity:entity]; + + @try { + //success + } + @catch (NSException * e) { + //fail + } + +} + +Response: +{ + "action" : "post", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items";, + "entities" : [ { + "uuid" : "0d7cf92a-effb-11e2-917d-c5e707256e71", + "type" : "item", + "name" : "milk", + "created" : 1374187231666, + "modified" : 1374187231666, + "metadata" : { + "path" : "/items/0d7cf92a-effb-11e2-917d-c5e707256e71" + }, + "name" : "milk", + "varieties" : [ { + "name" : "1%", + "price" : "3.25", + "SKU" : "0393847575533445" + }, { + "name" : "whole", + "price" : "3.85", + "SKU" : "0393394956788445" + }, { + "name" : "skim", + "price" : "4.00", + "SKU" : "0390299933488445" + } ] + } ], + "timestamp" : 1374187450826, + "duration" : 50, + "organization" : "your-org", + "applicationName" : "your-app" +} + + +### 8. Retrieving an entity + +SDK Method + + (ApigeeClientResponse *)getEntities: (NSString *)endpoint query:(NSString *)query + +Properties + +Parameter Description +--------- ----------- +endpoint The collection and entity identifier of the entity to be retrieved. +query An optional query string. Requests for a specific entity should set the value to nil + +Endpoint exported in the following format: <collection>/<entity_UUID_or_name> + +Example Request/Response + +Request: + + -(NSString*)getEntity { + + //specify the entity collection and UUID or name to be retrieved + NSString *endpoint = @"items/b3aad0a4-f322-11e2-a9c1-999e12039f87"; + + NSString *query = nil; + + //we recommend you call ApigeeClient from your AppDelegate. + //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios + //create an instance of AppDelegate + AppDelegate *appDelegate = (AppDelegate *)[[UIApplication sharedApplication] delegate]; + + //call getEntities to initiate the API call + ApigeeClientResponse *response = [appDelegate.dataClient getEntities:endpoint queryString:query]; + + @try { + //success + } + + @catch (NSException * e) { + //fail + } + + } + +Response: + + { + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/amuramoto/sandbox/items";, + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + } ], + "timestamp" : 1378405025763, + "duration" : 31, + "organization" : "amuramoto", + "applicationName" : "sandbox" + } + +### 9. Retrieving multiple entities + +SDK Method + + (ApigeeClientResponse *)getEntities: (NSString *)type queryString:(NSString *)queryString + +Properties + +Parameter Description +--------- ----------- +type The entity type being retrieved +queryString A query string of entity properties to be matched for the entities to be retrieved. + +Query string is expected in the following format: <property>=<value> OR <property>=<value> OR ... + +Example Request/Response + +Request: + + -(NSString*)getEntity { + + //specify the entity type to be retrieved + NSString *type = @"item"; + + //specify the uuid of the entity to be retrieved in a query string + NSString *query = @"uuid = b3aad0a4-f322-11e2-a9c1-999e12039f87 or name = 'bread'"; + + //we recommend you call ApigeeClient from your AppDelegate. + //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios + //create an instance of AppDelegate + AppDelegate *appDelegate = (AppDelegate *)[[UIApplication sharedApplication] delegate]; + + //call createEntity to initiate the API call + ApigeeClientResponse *response = [appDelegate.dataClient getEntities:type queryString:query]; + + @try { + //success + } + @catch (NSException * e) { + //fail + } + + } + +Response: + + { + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { + "ql" : [ "name='milk' OR UUID=1a9356ba-1682-11e3-a72a-81581bbaf055" ] + }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items";, + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + }, { + "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055", + "type" : "item", + "name" : "bread", + "created" : 1378423379867, + "modified" : 1378423379867, + "metadata" : { + "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055" + }, + "name" : "bread", + "price" : "2.50" + } ], + "timestamp" : 1378423793729, + "duration" : 63, + "organization" : "your-org", + "applicationName" : "your-app", + "count" : 2 + } + + +### 10. Updating an entity + +SDK Method + + (ApigeeClientResponse *)updateEntity: (NSString *)entityID entity:(NSDictionary *)updatedEntity + +Parameters + +Parameter Description +--------- ----------- +entityID UUID of the entity to be updated +updatedEntity NSMutableDictionary containing the properties to be updated + +Example Request/Response + +Request: + + -(NSString*)updateEntity { + + //UUID of the entity to be updated + NSString *entityID = @"f42752aa-08fe-11e3-8268-5bd5fa5f701f"; + + //Create an entity object + NSMutableDictionary *updatedEntity = [ [NSMutableDictionary alloc] init ]; + + //Set entity properties to be updated + [updatedEntity setObject:@"item" forKey:@"type"]; //Required - entity type + [updatedEntity setObject:@"in-stock" forKey:@"availability"]; + [updatedEntity setObject:@"4.00" forKey:@"price"]; + + //we recommend you call ApigeeClient from your AppDelegate. + //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios + //create an instance of AppDelegate + AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate]; + + //call updateEntity to initiate the API call + ApigeeClientResponse *response = [appDelegate.dataClient updateEntity:entityID entity:updatedEntity]; + + @try { + + //success + + } + @catch (NSException * e) { + //fail + } + + } + +Response: + + { + "action" : "put", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items";, + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378505705077, + "availability" : "in-stock", + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "4.00" + } ], + "timestamp" : 1378505705050, + "duration" : 87, + "organization" : "your-org", + "applicationName" : "your-app" + } + + +### 11. Updating a sub-property + +SDK Method + + (ApigeeClientResponse *)updateEntity: (NSString *)entityID entity:(NSDictionary *)updatedEntity + +Parameters + +Parameter Description +--------- ----------- +entityID UUID of the entity to be updated +updatedEntity Entity object containing the properties to be updated + +Example Request/Response + +Request: + + -(NSString*)updateEntity { + + //UUID of the entity to be updated + NSString *entityID = @"f42752aa-08fe-11e3-8268-5bd5fa5f701f"; + + //Define our two sub-properties to include in the update + NSMutableDictionary *subproperty1 = [ [NSMutableDictionary alloc] init]; + NSMutableDictionary *subproperty2 = [ [NSMutableDictionary alloc] init]; + [subproperty1 setObject:@"1%" forKey:@"name"]; + [subproperty1 setObject:@"3.25" forKey:@"price"]; + [subproperty2 setObject:@"whole" forKey:@"name"]; + [subproperty2 setObject:@"4.00" forKey:@"price"]; + + //Put our sub-properties into an NSArray + NSArray *subproperties = [ [NSArray alloc] initWithObjects:props1,props2, nil]; + + //Create an NSMutableDictionary to hold our updates + NSMutableDictionary *updatedEntity = [ [NSMutableDictionary alloc] init ]; + + //Set the properties to be updated + [updatedEntity setObject:@"item" forKey:@"type"]; //Required - entity type + [updatedEntity setObject:props forKey:@"varieties"]; + + //we recommend you call ApigeeClient from your AppDelegate. + //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios + //create an instance of AppDelegate + AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate]; + + //call createEntity to initiate the API call + ApigeeClientResponse *response = [appDelegate.dataClient updateEntity:entityID entity:updatedEntity]; + + @try { + + //success + + } + @catch (NSException * e) { + //fail + } + + } + +Response: + + { + "action" : "put", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items";, + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378761459069, + "availability" : "in-stock", + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "uri" : "http://api.usergrid.com/your-org/your-app/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4";, + "varieties" : [ { + "name" : "1%", + "price" : "3.25" + }, { + "name" : "whole", + "price" : "4.00" + } ] + } ], + "timestamp" : 1378761459047, + "duration" : 62, + "organization" : "your-org", + "applicationName" : "your-app" + } + + +### 12. Deleting data entities + +SDK Method + + (ApigeeClientResponse *)removeEntity: (NSString *)type entityID:(NSString *)entityID + +Properties + +Parameter Description +--------- ----------- +type The entity type being deleted +entityID The UUID or name of the entity to be removed + +Example Request/Response + +Request: + + -(NSString*)deleteEntity { + + //specify the entity type to be deleted + NSString *type = @"item"; + + //specify the uuid or name of the entity to be deleted + NSString *entityId = @"milk"; + + //we recommend you call ApigeeClient from your AppDelegate. + //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios + //create an instance of AppDelegate + AppDelegate *appDelegate = (AppDelegate *)[[UIApplication sharedApplication] delegate]; + + //call removeEntity to initiate the API call + ApigeeClientResponse *response = [appDelegate.dataClient removeEntity:type entityID:entityId]; + + @try { + //success + } + @catch (NSException * e) { + //fail + } + } + +Response: + + { + "action" : "delete", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items";, + "entities" : [ { + "uuid" : "328fe64a-19a0-11e3-8a2a-ebc6f49d1fc4", + "type" : "item", + "name" : "milk", + "created" : 1378766158500, + "modified" : 1378766158500, + "metadata" : { + "path" : "/items/328fe64a-19a0-11e3-8a2a-ebc6f49d1fc4" + }, + "name" : "milk", + "price" : "3.25" + } ], + "timestamp" : 1378766172016, + "duration" : 324, + "organization" : "your-org", + "applicationName" : "your-app" + } + + +## Data Queries + +### 13. Querying your data + +## Entity Connections + +### 14. Connecting users other data +### 15. Retrieving user connection data +### 16. Disconnecting entities + +## Permissions & Roles + +### 17. Assigning permissions +### 18. Removing permissions +### 19. Assigning permissions +### 20. Removing permissions +### 21. Creating roles +### 22. Assigning roles +### 23. Removing roles + +## Authentication + +### 24. Application user authentication (user login) +### 25. Application client authentication +### 26. Admin user authentication +### 27. Organization client authentication +### 28. Revoking tokens (user logout) + +# Working with Users & Groups + +### 29. Creating users +### 30. Retrieving user data +### 31. Setting or updating password +### 32. Creating groups +### 33. Retrieving group data +### 34. Retrieving a group's users +### 35. Adding users groups +### 36. Deleting user group + +## Activities & Feeds + +### 37. Posting a user activity +### 38. Posting an activity to a group +### 39. Creating an activity for a user's followers in a group +### 40. Retrieving a user's activity feed +### 41. Retrieving a group's activity feed + +## Events & Counters + +### 42. Creating & incrementing counters +### 43. Retrieving counters +### 44. Retrieving counters by time interval + +## Managing Orgs & Apps + +### 46. Creating an organization +### 47. Getting an organization +### 48. Activating an organization +### 49. Reactivating an organization +### 50. Generating organization client credentials +### 51. Retrieving organization client credentials +### 52. Getting an organization's activity feed +### 53. Getting the applications in an organization +### 54. Getting the admin users in an organization +### 55. Removing an admin user from an organization +### 56. Creating an organization application +### 57. Generating application credentials +### 58. Getting application credentials + +## Managing Admin Users + +### 59. Creating an admin user +### 60. Updating an admin user +### 61. Getting an admin user +### 62. Setting an admin user's password +### 63. Resetting an admin user's password +### 64. Activating an admin user +### 65. Reactivating an admin user +### 66. Getting an admin user's activity feed + + \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/sdks/ios.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/sdks/ios.txt b/content/docs/_sources/sdks/ios.txt index 328b09a..b0ba069 100644 --- a/content/docs/_sources/sdks/ios.txt +++ b/content/docs/_sources/sdks/ios.txt @@ -1 +1,107 @@ -# iOS SDK \ No newline at end of file +# iOS SDK + +##Version + +Current Version: **0.9.2** + +Change log: + +<https://github.com/apigee/usergrid-javascript-sdk/blob/master/changelog.md> + +##Overview +This open source SDK simplifies writing iOS applications that connect to App Services (Usergrid). The repo is located here: + +<https://github.com/apigee/usergrid-ios-sdk> + +You can download the SDK here: + +* Download as a zip file: <https://github.com/apigee/usergrid-ios-sdk/archive/master.zip> +* Download as a tar.gz file: <https://github.com/apigee/usergrid-ios-sdk/archive/master.tar.gz> + + +To find out more about App Services, which is Apigee's hosted Usergrid solution, see: + +<http://apigee.com/about/developers> + +To view the Apigee App Services documentation, see: + +<http://apigee.com/docs/app_services> + + +##Installing +Once you have downloaded the SDK, add the UGAPI folder to your project by dragging and dropping it into your project. + +**Note:** Make sure you check the "Copy items into destination group's folder", and also make sure the appropriate boxes are checked next to "Add to targets". + + +##Getting started +If you haven't done so, make sure you know your organization name and your application name. Your organization name will be the same as the username you signed up with. + +Within your organization, you can have multiple application namespaces. By default, an application named "Sandbox" has been created for you to use for testing, but you can also log into the [Admin Portal](http://apigee.com/usergrid) and create an application with any name you want. + +Once you have your application name, you will want to create a UGClient object like so: + + //configure the org and app + NSString * orgName = @"ApigeeOrg"; + NSString * appName = @"MessageeApp"; + + //make new client + usergridClient = [[UGClient alloc]initWithOrganizationId: orgName withApplicationID: appName]; + +Now use the usergridClient object to invoke other methods that access the API. For example, to log a user in: + + [usergridClient logInUser:username password:password]; + UGUser *user = [usergridClient getLoggedInUser]; + +Or, to create a user: + + UGClientResponse *response = [usergridClient addUser:@"myusername" email:@"em...@email.com" name:@"my name" password:@"mypassword"]; + if (response.transactionState == 0) { + //user created! + } + + +##Sample Code +If you are ready to look at a fully functional app that uses this SDK, check out our Messagee application. It is a twitter-type app that exercises many parts of the API including: Login / Authentication, GET and POST operations, activities (tweets), and social features such as following relationships. + +The Messagee Xcode project is located here: + +<https://github.com/apigee/usergrid-sample-ios-messagee> + +##Running Tests + +The iOS SDK unit tests are written with Nu. You'll need to install the language itself to run the tests, and use the Nukefile to create a Usergrid.framework. For installation directions go [here](https://github.com/timburks/nu) + +To compile the Usergrid SDK as an Objective-C framework simple type `nuke` to build the framework and then `nuke install` to install it in the /Library/Frameworks path. + +To run the unit tests written for the SDK use the command `nuke test` this will run all tests. + +## Contributing +We welcome your enhancements! + +Like [Usergrid](https://github.com/apigee/usergrid-node-module), the Usergrid Objective-C SDK is open source and licensed under the Apache License, Version 2.0. + +1. Fork it +2. Create your feature branch (`git checkout -b my-new-feature`) +3. Commit your changes (`git commit -am 'Added some feature'`) +4. Push your changes to the upstream branch (`git push origin my-new-feature`) +5. Create new Pull Request (make sure you describe what you did and why your mod is needed) + +##More information +For more information on Apigee App Services, visit <http://apigee.com/about/developers>. + + +## Copyright +Copyright 2013 Apigee Corporation + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +<http://www.apache.org/licenses/LICENSE-2.0> + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/sdks/sdk-outline.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/sdks/sdk-outline.txt b/content/docs/_sources/sdks/sdk-outline.txt new file mode 100644 index 0000000..48bd3fc --- /dev/null +++ b/content/docs/_sources/sdks/sdk-outline.txt @@ -0,0 +1,111 @@ +# Usergrid SDK Documentation outline + +## Getting Started + +### Installing the SDK +### Building from Source + +# Usergrid SDK Reference with Examples + +The 66 topics listed below are each documented in the Usergrid documentation and +for each the docs provide an API reference and example for each of these clients: +curl, iOS, Android, JavaScript, Ruby and Node.js. + +## Working with Collections + +### 1. Creating collections +### 2. Retrieving collections +### 3. Updating collections +### 4. Deleting collections + +## Working with Entities + +### 5. Creating a custom entity +### 6. Creating multiple custom entities +### 7. Creating an entity with sub-properties +### 8. Retrieving an entity +### 9. Retrieving multiple entities +### 10. Updating an entity +### 11. Updating a sub-property +### 12. Deleting data entities + +## Data Queries + +### 13. Querying your data + +## Entity Connections + +### 14. Connecting users other data +### 15. Retrieving user connection data +### 16. Disconnecting entities + +## Permissions & Roles + +### 17. Assigning permissions +### 18. Removing permissions +### 19. Assigning permissions +### 20. Removing permissions +### 21. Creating roles +### 22. Assigning roles +### 23. Removing roles + +## Authentication + +### 24. Application user authentication (user login) +### 25. Application client authentication +### 26. Admin user authentication +### 27. Organization client authentication +### 28. Revoking tokens (user logout) + +# Working with Users & Groups + +### 29. Creating users +### 30. Retrieving user data +### 31. Setting or updating password +### 32. Creating groups +### 33. Retrieving group data +### 34. Retrieving a group's users +### 35. Adding users groups +### 36. Deleting user group + +## Activities & Feeds + +### 37. Posting a user activity +### 38. Posting an activity to a group +### 39. Creating an activity for a user's followers in a group +### 40. Retrieving a user's activity feed +### 41. Retrieving a group's activity feed + +## Events & Counters + +### 42. Creating & incrementing counters +### 43. Retrieving counters +### 44. Retrieving counters by time interval + +## Managing Orgs & Apps + +### 46. Creating an organization +### 47. Getting an organization +### 48. Activating an organization +### 49. Reactivating an organization +### 50. Generating organization client credentials +### 51. Retrieving organization client credentials +### 52. Getting an organization's activity feed +### 53. Getting the applications in an organization +### 54. Getting the admin users in an organization +### 55. Removing an admin user from an organization +### 56. Creating an organization application +### 57. Generating application credentials +### 58. Getting application credentials + +## Managing Admin Users + +### 59. Creating an admin user +### 60. Updating an admin user +### 61. Getting an admin user +### 62. Setting an admin user's password +### 63. Resetting an admin user's password +### 64. Activating an admin user +### 65. Reactivating an admin user +### 66. Getting an admin user's activity feed + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/security-and-auth/authenticating-api-requests.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/authenticating-api-requests.txt b/content/docs/_sources/security-and-auth/authenticating-api-requests.txt index af52bf6..d29e4cb 100644 --- a/content/docs/_sources/security-and-auth/authenticating-api-requests.txt +++ b/content/docs/_sources/security-and-auth/authenticating-api-requests.txt @@ -4,7 +4,7 @@ With the exception of the 'sandbox' application that is created with every Userg This article describes how to use access tokens to access the Usergrid API, and how to manage access tokens, including revoking and changing token time to live. -For information on generating access tokens/authenticating users and clients, see Authenticating users and application clients. +For information on generating access tokens/authenticating users and clients, see [Authenticating users and application clients](../security-and-auth/authenticating-users-and-application-clients.html). ## Authenticating with access tokens When you obtain an access token, you must provide it with every subsequent API call that you make. There are two ways to provide your access token. @@ -18,7 +18,7 @@ You can include the token in an HTTP authorization header: Authorization: Bearer {access_token} <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">⨠-Note: The Usergrid documentation assumes you are providing a valid access token with every API call whether or not it is shown explicitly in the examples. Unless the documentation specifically says that you can access an API endpoint without an access token, you should assume that you must provide it. One application that does not require an access token is the sandbox application. The Guest role has been given full permissions (/** for GET, POST, PUT, and DELETE) for this application. This eliminates the need for a token when making application level calls to the sandbox app. For further information on specifying permissions, see Managing access by defining permission rules. +Note: The Usergrid documentation assumes you are providing a valid access token with every API call whether or not it is shown explicitly in the examples. Unless the documentation specifically says that you can access an API endpoint without an access token, you should assume that you must provide it. One application that does not require an access token is the sandbox application. The Guest role has been given full permissions (/** for GET, POST, PUT, and DELETE) for this application. This eliminates the need for a token when making application level calls to the sandbox app. For further information on specifying permissions, see [Using Permissions](security-and-auth/using-permissions.html). </p></div> ## Authenticating with client ID and client secret @@ -27,7 +27,7 @@ Another option for authenticating your API requests is using either your organiz <div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠Warning: For server-side use only -You should never authenticate this way from a client-side app such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. See Security best practices for additional considerations in keeping access to your app and its data secure. +You should never authenticate this way from a client-side app such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. See [Security Best Practices](../security-and-auth/securing-your-app.html) for additional considerations in keeping access to your app and its data secure. </p></div> This can be a convenient way to authenticate API requests, since there is no need to generate and manage an access token, but please note that you should be very cautious when implementing this type of authentication. Organization-level authentication grants full permission to perform any supported call against your organization and every application in it, and application-level authentication grants full permission to perform any supported call against all of the resources in an application. Should your client id and client secret be compromised, a malicious user would gain broad access to your organization or application. http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/security-and-auth/authenticating-users-and-application-clients.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/authenticating-users-and-application-clients.txt b/content/docs/_sources/security-and-auth/authenticating-users-and-application-clients.txt index eaa52f4..e1ada48 100644 --- a/content/docs/_sources/security-and-auth/authenticating-users-and-application-clients.txt +++ b/content/docs/_sources/security-and-auth/authenticating-users-and-application-clients.txt @@ -49,7 +49,7 @@ The results include the access token needed to make subsequent API requests on b Using your appâs client id and client secret values, your app can connect to the Usergrid application endpoint to request an access token. The client ID and secret for your app can be found in 'Getting Started' section of the API Services admin portal, under 'Server App Credentials'. <div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠-Warning: You should never authenticate this way from a client-side app such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. See "safe mobile access" in [Authenticating API requests](authenticating-api-requests.html) for additional considerations in keeping access to your app and its data secure. +Warning: You should never authenticate this way from a client-side app such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. See [Security Best Practices](../security-and-auth/securing-your-app.html) for additional considerations in keeping access to your app and its data secure. </p></div> ### Request syntax @@ -76,7 +76,7 @@ The results include the access token needed to make subsequent API requests on b If you do require admin user access, your app can connect to the Usergrid management endpoint to request an access token. Your app supplies the username and password of an admin user in the request. <div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠-Warning: Authenticating as an admin user grants full access to one or more organizations and all of the applications contained in those organizations. Due to this, be cautious when implementing this type of authentication in client-side code. Instead, consider implementing admin user access in server-side code only. See "safe mobile access" in [Authenticating API requests](authenticating-api-requests.html) for additional considerations in keeping access to your app and its data secure. +Warning: Authenticating as an admin user grants full access to one or more organizations and all of the applications contained in those organizations. Due to this, be cautious when implementing this type of authentication in client-side code. Instead, consider implementing admin user access in server-side code only. See [Security Best Practices](../security-and-auth/securing-your-app.html) for additional considerations in keeping access to your app and its data secure. </p></div> ### Request syntax @@ -103,7 +103,7 @@ The results include the access token needed to make subsequent API requests on b If you do require organization level access, your app can connect to the Usergrid management endpoint to request an access token. Access to an organization requires the client id and client secret credentials. The client ID and secret for your organization can be found on the 'Org Administration' page of the API Services admin console under 'Organization API Credentials'. <div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠-Warning: You should never authenticate this way from a client-side app such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. See "safe mobile access" in [Authenticating API requests](authenticating-api-requests.html for additional considerations in keeping access to your app and its data secure. +Warning: You should never authenticate this way from a client-side app such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. See [Security Best Practices](../security-and-auth/securing-your-app.html) for additional considerations in keeping access to your app and its data secure. </p></div> ### Request syntax http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/security-and-auth/facebook-sign.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/facebook-sign.txt b/content/docs/_sources/security-and-auth/facebook-sign.txt index e2c7411..970cb33 100644 --- a/content/docs/_sources/security-and-auth/facebook-sign.txt +++ b/content/docs/_sources/security-and-auth/facebook-sign.txt @@ -21,7 +21,7 @@ where: ## Facebook login example The Facebook technical guides for login present detailed information on how to add Facebook login to your app. Instructions are provided for JavaScript, iOS, and Android. -In brief, here are the steps for JavaScript. You can see these steps implemented in the Facebook login example packaged with the JavaScript SDK for Usergrid (which you can download in ZIP format or tar.gz format). The Facebook login example is in the /examples/facebook directory of the extracted download. The code example snippets shown below are taken from the Facebook login example. +In brief, here are the steps for JavaScript. You can see these steps implemented in the Facebook login example packaged with the JavaScript SDK for Usergrid (which you can download in ZIP format or tar.gz format). The Facebook login example is in the ``/examples/facebook`` directory of the extracted download. The code example snippets shown below are taken from the Facebook login example. ### Step 1: Create a Facebook app Create a new app on the Facebook App Dashboard. Enter your app's basic information. Once created, note the app ID shown at the top of the dashboard page. http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/security-and-auth/user-authentication-types.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/user-authentication-types.txt b/content/docs/_sources/security-and-auth/user-authentication-types.txt index 1a14f50..d02e8d3 100644 --- a/content/docs/_sources/security-and-auth/user-authentication-types.txt +++ b/content/docs/_sources/security-and-auth/user-authentication-types.txt @@ -5,7 +5,7 @@ Usergrid supports four levels of authentication, but only one of them is used wh ## Configuring authentication levels Access permissions can only be configured for the 'application user' â this can be done both programmatically and in the admin portal. The application, organization and admin clients cannot be configured, and can only be accessed programmatically via the API. -For more about creating and managing roles and permissions for application users, see Managing access by defining permission rules. For a look at how security features fit together, see App Security Overview. +For more about creating and managing roles and permissions for application users, see [Using Permissions](security-and-auth/using-permissions.html) and [Using Roles](security-and-auth/using-roles.html). For a look at how security features fit together, see [App Security Overview](../security-and-auth/app-security.html). ## User authentication level @@ -16,14 +16,14 @@ For more about creating and managing roles and permissions for application users </tr> <tr> <td>Application user</td> - <td>This is the standard authentication type you will use to implement user login for your app. The application user level allows access to your Usergrid application as governed by the permission rules you create and associated with users and user groups. For more on setting permissions see Managing access by defining permission rules. Each Application User is represented by a User entity in your Usergrid application. For more about the User entity, see User.</td> + <td>This is the standard authentication type you will use to implement user login for your app. The application user level allows access to your Usergrid application as governed by the permission rules you create and associated with users and user groups. For more on setting permissions see [Using Permissions](security-and-auth/using-permissions.html). Each Application User is represented by a User entity in your Usergrid application. For more about the User entity, see User.</td> </tr> </table> ## Admin authentication levels <div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠-Warning: Safe use of admin authentication levels. Never use client ID and client secret, or any hard-coded credentials to authenticate this way from a client-side app, such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. Even when authenticating with username and password, be cautious when using these authentication levels since they grant broad access to your Usergrid account. See "safe mobile access" in Authenticating API requests for additional considerations in keeping access to your app and its data secure.</p></div> +Warning: Safe use of admin authentication levels. Never use client ID and client secret, or any hard-coded credentials to authenticate this way from a client-side app, such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. Even when authenticating with username and password, be cautious when using these authentication levels since they grant broad access to your Usergrid account. See [Security Best Practices](../security-and-auth/securing-your-app.html) for additional considerations in keeping access to your app and its data secure.</p></div> <table class="usergrid-table"> <tr> http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/security-and-auth/using-permissions.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/using-permissions.txt b/content/docs/_sources/security-and-auth/using-permissions.txt index 34ec664..1454d11 100644 --- a/content/docs/_sources/security-and-auth/using-permissions.txt +++ b/content/docs/_sources/security-and-auth/using-permissions.txt @@ -33,7 +33,7 @@ Complex paths can be defined using [Apache Ant pattern syntax](http://ant.apache </table> ## Assigning permissions -Permissions can only be assigned to user, group or role entities. Assigning permissions to roles can be particularly useful, as it allows you to create sets of permissions that represent complex access definitions, which can then be assigned to user and group entities. For more on roles, see Using roles. +Permissions can only be assigned to user, group or role entities. Assigning permissions to roles can be particularly useful, as it allows you to create sets of permissions that represent complex access definitions, which can then be assigned to user and group entities. For more on roles, see [Using Roles](security-and-auth/using-roles.html). ### Request syntax @@ -47,7 +47,7 @@ org Organization UUID or organization name app Application UUID or application name collection The collection of the entity that the permissions are to be assigned to. entity The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted. -permissions The permissions to assign to the entity. See Permissions syntax for format. +permissions The permissions to assign to the entity. See [Permissions syntax](security-and-auth/using-permissions.html#permissions-syntax) for format. For collections, Valid values are users and groups. http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/security-and-auth/using-roles.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/using-roles.txt b/content/docs/_sources/security-and-auth/using-roles.txt new file mode 100644 index 0000000..2a794e3 --- /dev/null +++ b/content/docs/_sources/security-and-auth/using-roles.txt @@ -0,0 +1,304 @@ +# Using roles +Roles are named sets of one or more permissions, and are useful for defining specific access levels to resources in your Usergrid data store. Multiple roles can be assigned to a user or group, giving you a great deal of flexibility in how access to resources are defined. + +For example, in a blogging app you might create a 'reviewer' role that allows GET and PUT access to an articles collection to allow the user to retrieve and update articles, but not allow them to create new articles. + +## Default roles +While you can create as many custom roles as you want per application, all Usegrid applications include three default roles. These roles each serve a special purpose and should not be deleted; however, you can and should adjust the permissions assigned to these roles to suit the needs of you app. + +The following table describes each pre-defined role, and the permissions that are assigned to them by default. + +<table class="usergrid-table"> +<tr> + <th>Role</th> + <th class="usergrid-30"> Permissions</th> + <th>Description</th> +</tr> +<tr> + <td>Guest</td> + <td> + +* post: /devices +* post: /users +* put: /devices/* + + </td> + <td> + + Assigned to all unauthenticated requests. Includes a basic set of permissions that are commonly needed by unregistered or unauthenticated users. + <p>Grants permission for a user to create a user account and for their device to be registered. + + </td> +</tr> +<tr> + <td>Default</td> + <td> + +* get, post, put, delete: /** + + </td> + <td> + +Default for authenticated users. Assigns the associated permissions to all users whose requests are authenticated with a valid access token. + +<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠+By default, __grants full access for all resources in your application__. A first task in securing your application should be to restrict access by redefining this role to narrow the access it provides. Remove the default full permission rule and add restrictive permission rules for a production deployment. +</p></div> + + </td> +</tr> +<tr> + <td>Administrator</td> + <td>None</td> + <td> + +Unused until you associate it with users or groups. By default, includes no permissions that provide access. Grants no access. Consider this a blank slate. Add permission rules and associate this role with users and groups as needed. +<div class="admonition note"> <p class="first admonition-title">NOTE</p> <p class="last">⨠+The Administrator role is <i>not</i> the same as an organization administrator, that is, someone who authenticates as an Admin User. The Admin User is an implicit user created when you create an organization. After authenticating, the Admin User has full access to all of the administration features of the Usergrid API. By comparison, the Administrator role is simply a role (initially without permissions) that can be assigned to any user. +</p></div> + + </td> +</tr> +</table> + +## Creating roles +Generally, it is easiest to a create a role for each access type you want to enable in your app. You may, however, assign multiple roles to any user or group entity, so you have the flexibility to define any schema for applying roles that you like. + +The following shows how to create a new role and assign permissions to it. + +### Request syntax +With cURL requests a role entity is created with a POST request, then permissions must be assigned to it with a separate request. For more on assigning permissions with cURL, see [Using Permissions](security-and-auth/using-permissions.html). + +The following details how to create a new role entity. + + curl -X POST https://api.usergrid.com/<org>/<app>/roles -d '{"name":<roleName>}' + +Parameters + +Parameter Description +--------- ----------- +org Organization UUID or organization name +app Application UUID or application name +roleName The name of the role to be created + +### Example request + + curl -X POST "https://api.usergrid.com/my-org/my-app/roles/ -d '{"name":"manager"}' + +### Example response + + { + "action" : "post", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/roles", + "uri" : "https://api.usergrid.com/your-org/your-app/roles";, + "entities" : [ { + "uuid" : "382d0991-74bb-3548-8166-6b07e44495ef", + "type" : "role", + "name" : "manager", + "created" : 1402612783104, + "modified" : 1402612783104, + "roleName" : "manager", + "title" : "manager", + "inactivity" : 0, + "metadata" : { + "path" : "/roles/382d0991-74bb-3548-8166-6b07e44495ef", + "sets" : { + "permissions" : "/roles/382d0991-74bb-3548-8166-6b07e44495ef/permissions" + }, + "collections" : { + "groups" : "/roles/382d0991-74bb-3548-8166-6b07e44495ef/groups", + "users" : "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users" + } + } + } ], + "timestamp" : 1402612783102, + "duration" : 30, + "organization" : "your-org", + "applicationName" : "your-app" + } + + +### Creating Roles in the Admin Portal + +1. In the left sidebar of the Usergrid portal, click Users > Roles. This displays the roles defined for the application. +Click the '+' button. +2. In the dialog box, provide a 'title' and 'role name.' A title is an alias for the role name. +3. Click 'Create'. The role will be created, but will not have any permissions assigned to it. +4. Click the role you created in the list. +5. Click the 'Add permissions' button. +6. In the dialog box, click the check boxes for the HTTP methods you want to grant permissions for, and enter the resource path in the 'Path' field. +7. The 'Inactivity' field lets you control automatic user logout during periods of inactivity. Set a number of seconds of inactivity before users assigned to this role are automatically logged out. + +## Assigning roles +Once you have created some roles, you will need to explicitly assign them to a user or group entity. The permissions associated with that role will be granted to the entity immediately for any requests they send that are authenticated by a valid access token. Please note that assigning a role to a group will grant the associated permissions to every user in that group. + +The following shows how to assign a role to an entity. + +### Request syntax + + curl -X POST https://api.usergrid.com/<org>/<app>/roles/<roleName>/<entityType>/<entityID> + +Parameters + +Parameter Description +--------- ----------- +org Organization UUID or organization name +app Application UUID or application name +roleName The name of the role to be created +entityType The type of the entity the role is being assigned to. 'Group' and 'user' are valid values. +entityID The UUID of the entity the role is being assigned to. + +For groups, the 'name' property can be used. For users, the 'username' property can be used. + +### Example request + + curl -X POST "https://api.usergrid.com/my-org/my-app/roles/manager/users/someUser + + +### Example response + + { + "action" : "post", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users", + "uri" : "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users";, + "entities" : [ { + "uuid" : "410b213a-b379-11e3-a0e5-9953085ea376", + "type" : "user", + "name" : "someUser", + "created" : 1395681911491, + "modified" : 1399070010291, + "username" : "someUser", + "activated" : true, + "file" : "fobnszewobnioerabnoiawegbrn\n", + "metadata" : { + "connecting" : { + "friends" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/friends", + "likes" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/likes" + }, + "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376", + "sets" : { + "rolenames" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles", + "permissions" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/permissions" + }, + "connections" : { + "completed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/completed", + "follows" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/follows" + }, + "collections" : { + "activities" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/activities", + "devices" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/devices", + "feed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/feed", + "groups" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/groups", + "roles" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles", + "following" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/following", + "followers" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/followers" + } + } + } ], + "timestamp" : 1402965083889, + "duration" : 41, + "organization" : "your-org", + "applicationName" : "your-app" + } + + +### Assigning Roles in the Admin Portal + +The easiest way to assign roles to user or group entities is to use the 'Users' tab of the Usergrid admin portal, by doing the following: + +1. In the left sidebar of the admin portal, click Users > Users or Users > Groups to display either the list of users or groups in your application. +2. In the list, click the name of the user or group entity you want to assign roles to to display its details in the right pane. +3. Click the 'Roles & Permissions' tab above the right pane. +4. Click the 'Add Role' button. +5. In the popup, select a role from the drop down menu. +6. Click the 'Add' button. + + +## Removing roles +At times it may be necessary to remove a role from a user or group entity, for example if a user changes jobs, or the duties of a group are altered. Please note that removing a role from a group will remove the associated permissions from every user in that group. + +The following shows how to remove a role from an entity. + +### Request syntax + + curl -X DELETE https://api.usergrid.com/<org>/<app>/roles/<roleName>/<entityType>/<entityID> + +Parameters + +Parameter Description +--------- ----------- +org Organization UUID or organization name +app Application UUID or application name +roleName The name of the role to be created +entityType The type of the entity the role is being removed from. 'Group' and 'user' are valid values. +entityID The UUID of the entity the role is being removed from. + +For groups, the 'name' property can be used. For users, the 'username' property can be used. + +### Example request + + curl -X DELETE https://api.usergrid.com/my-org/my-app/roles/manager/users/someUser + + +### Example response + + { + "action" : "delete", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users", + "uri" : "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users";, + "entities" : [ { + "uuid" : "410b213a-b379-11e3-a0e5-9953085ea376", + "type" : "user", + "name" : "someUser", + "created" : 1395681911491, + "modified" : 1399070010291, + "username" : "someUser", + "activated" : true, + "metadata" : { + "connecting" : { + "friends" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/friends", + "likes" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/likes" + }, + "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376", + "sets" : { + "rolenames" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles", + "permissions" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/permissions" + }, + "connections" : { + "completed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/completed", + "follows" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/follows" + }, + "collections" : { + "activities" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/activities", + "devices" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/devices", + "feed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/feed", + "groups" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/groups", + "roles" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles", + "following" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/following", + "followers" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/followers" + } + } + } ], + "timestamp" : 1403214283808, + "duration" : 358, + "organization" : "your-org", + "applicationName" : "your-app" + } + +### Removing Roles in the Admin Portal + +The easiest way to remove roles from user or group entities is to use the 'Users' tab of the Usergrid admin portal, by doing the following: + +1. In the left sidebar of the Usergrid admin portal, click Users > Users or Users > Groups to display either the list of users or groups in your application. +2. In the list, click the name of the user or group entity you want to remove roles from to display its details in the right pane. +3. Click the 'Roles & Permissions' tab above the right pane. +4. Click the role you created in the list. +5. Under 'Roles', click the checkbox beside the role you want to remove from the entity. +6. Click the 'Leave roles' button. + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/user-management/activity.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/user-management/activity.txt b/content/docs/_sources/user-management/activity.txt index 2703ab8..4f09c8b 100644 --- a/content/docs/_sources/user-management/activity.txt +++ b/content/docs/_sources/user-management/activity.txt @@ -16,13 +16,13 @@ information about these actions). When a user creates an activity, it creates a relationship between the activity and the user who created it. Because this relationship exists, the activity will appear in the feed of any of the userâs followers. -Think of the Activities endpoint (/users/{uuid|username}/activities) as +Think of the Activities endpoint (``/users/{uuid|username}/activities``) as an "outbox" of news items created by the user. Think of the Feed -endpoint (/users/{uuid|username}/feed) as an "inbox" of news items meant +endpoint (``/users/{uuid|username}/feed``) as an "inbox" of news items meant to be seen or consumed by the user. A user can also post an activity to a group (located at -/groups/{uuid|groupname}/activities). This allows you to emulate +``/groups/{uuid|groupname}/activities``). This allows you to emulate Facebook-style group functionality, where a limited number of users can share content on a common "wall". In any of these cases, there is no need to construct publish/subscribe relationships manually. @@ -36,10 +36,9 @@ to the user's activity stream for display as well as to the activity streams of any of the user's followers. Using Usergrid APIs you can create, retrieve, update, and delete -activity entities. See You do not have access to view this node for -descriptions of these APIs. +activity entities. -**Note:** Although not shown in the API examples below, you need to +__Note:__ Although not shown in the API examples below, you need to provide a valid access token with each API call. See [Authenticating users and application clients](../security-and-auth/authenticating-users-and-application-clients.html) for details. @@ -131,13 +130,13 @@ The ``/users/me`` endpoint is accessible only if you provide an access token wit When you create an activity it creates a relationship between the activity and the user who created it. In other words, the newly created activity above belongs to john.doe. Another way of saying this is the user "owns" the activity. And because this relationship exists, the activity will appear in the feed of any of the userâs followers (in this example, anyone who is following john.doe). However, it will not appear in the feed of people the user follows. The activity is accessible at the ``/activities`` endpoint to users who have the permission to read that endpoint. -Notice the properties specified in the request body in the previous example are actor, verb, and content. The actor, verb, and content properties are built into the Activity entity (see Default Data Entity Types). The actor property specifies properties of the entity that performs the action (here, user john.doe). The gravatar URL is used to create an icon for the activity. And because an Activity is simply an API Services data entity, you can also create custom properties. +Notice the properties specified in the request body in the previous example are actor, verb, and content. The actor, verb, and content properties are built into the Activity entity (see [Activity entity properties](../rest-endpoints/api-doc.html#activity) ). The actor property specifies properties of the entity that performs the action (here, user john.doe). The gravatar URL is used to create an icon for the activity. And because an Activity is simply an API Services data entity, you can also create custom properties. The verb parameter is descriptive. You can use it to indicate what type of activity is posted, for example, an image versus text. The value post is defined in the JSON Activity Streams specification as âthe act of authoring an object and then publishing it online.â ## Posting an activity to a group -Use the POST method to post an activity to a specific group. In this case the activity is created in the activities collection and is accessible at the /activities endpoint to users who have the permission to read that endpoint. In addition, a relationship is established between the activity and the group, and because of that, the activity will appear in the groupâs feed. The group "owns" the activity. Also, the activity will be published in the feed of all users that are members of the group. +Use the POST method to post an activity to a specific group. In this case the activity is created in the activities collection and is accessible at the ``/activities`` endpoint to users who have the permission to read that endpoint. In addition, a relationship is established between the activity and the group, and because of that, the activity will appear in the groupâs feed. The group "owns" the activity. Also, the activity will be published in the feed of all users that are members of the group. ### Request URI @@ -223,7 +222,7 @@ When you create an activity for a userâs followers in a group: The activity is accessible at the ``/activities`` endpoint to users who have the permission to read that endpoint. The activity will not be cross-posted to the groupâs activity endpoint (``/groups/{uuid|groupname}/activities``) A relationship is automatically created between the activity entity that was just created and the user within that group (``/groups/{uuid|groupname}/users/{uuid|username}``) -The user within the group (``/groups/{uuid|groupname}/users/{uuid|username}```) becomes the owner of the activity (through the owner property in the activity). +The user within the group (``/groups/{uuid|groupname}/users/{uuid|username}``) becomes the owner of the activity (through the owner property in the activity). ### Request URI http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/user-management/group.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/user-management/group.txt b/content/docs/_sources/user-management/group.txt index 4f76cb6..a48606b 100644 --- a/content/docs/_sources/user-management/group.txt +++ b/content/docs/_sources/user-management/group.txt @@ -10,7 +10,7 @@ See the [Group Model section of the API Reference](../rest-endpoints/api-docs.ht ## Creating groups -A group entity represents an application group of users. You can create, retrieve, update, delete, and query group entities. See User entity properties for a list of the system-defined properties for group entities. In addition, you can create group properties specific to your application. +A group entity represents an application group of users. You can create, retrieve, update, delete, and query group entities. See [User entity properties](../rest-endpoints/api-doc.html#user) for a list of the system-defined properties for group entities. In addition, you can create group properties specific to your application. ### Request Syntax @@ -39,7 +39,7 @@ The ``path`` property is required and must be unique, it may include forward sla ### Example -__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details. +__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See [Authenticating users and application clients](../security-and-auth/authenticating-users-and-application-clients.html) for details. ### Request @@ -104,7 +104,7 @@ Parameter Description org_id | uuid Organization UUID or organization name app_id | uuid Application UUID or application name groupPath | uuid Group UUID or group path, which must be unique. -query_string A data store query. For more on queries, see Data queries. +query_string A data store query. For more on queries, see [Data queries](../data-queries/querying-your-data.html). ### Request @@ -225,11 +225,9 @@ For more information and code samples, see [Deleting Data Entities](../data-stor ## Adding a user to a group -See all application entities - You can add users to groups from client code using cURL commands or one of the SDKs, as described here. -When setting up your application on the server, you might find it easier and more convenient to create and populate groups with the admin portal. There, you can create groups, create roles, and define permission rules that govern user access to data and services in your application. For more information, see Security & token authentication. +When setting up your application on the server, you might find it easier and more convenient to create and populate groups with the admin portal. There, you can create groups, create roles, and define permission rules that govern user access to data and services in your application. For more information, see [Security & Token Authentication](../security-and-auth/app-security.html). Use the POST method to add a user to a group. If the named group does not yet exist, an error message is returned. @@ -252,7 +250,7 @@ arg uuid | string username UUID or username of user ### Example -__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details. +__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See [Authenticating users and application clients](../security-and-auth/authenticating-users-and-application-clients.html) for details. ### Request http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/user-management/messagee-example.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/user-management/messagee-example.txt b/content/docs/_sources/user-management/messagee-example.txt index eb3e560..1401d8c 100644 --- a/content/docs/_sources/user-management/messagee-example.txt +++ b/content/docs/_sources/user-management/messagee-example.txt @@ -8,7 +8,7 @@ There are three client versions of Messagee: * [An Android client version](https://github.com/apigee/usergrid-sample-android-messagee) * [An HTML5 client](https://github.com/apigee/usergrid-sample-html5-messagee) -The sections below describe how to create a new app, enter some test users, and run the app. You also learn how to use the Usergrid admin portal, a user interface that streamlines data and application management in the Usergrid system. The portal is also a reference application that shows how to incorporate Usergrid APIs with JavaScript. For a more detailed discussion of the portal's functionality, see Admin portal. +The sections below describe how to create a new app, enter some test users, and run the app. You also learn how to use the Usergrid admin portal, a user interface that streamlines data and application management in the Usergrid system. The portal is also a reference application that shows how to incorporate Usergrid APIs with JavaScript. ## Creating a user account in Usergrid http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/7662bc94/content/docs/_sources/user-management/working-user-data.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/user-management/working-user-data.txt b/content/docs/_sources/user-management/working-user-data.txt index a7603fd..5e2b63d 100644 --- a/content/docs/_sources/user-management/working-user-data.txt +++ b/content/docs/_sources/user-management/working-user-data.txt @@ -1,7 +1,7 @@ # Working with User Data You can store and manage user data as User entities. With user data in your application, you can add support for a wide variety of features common to mobile apps. For example, you can: -* Control access to data by defining permission rules. (See Security & token authentication for more.) +* Control access to data by defining permission rules. (See [Security & token authentication](../security-and-auth/app-security.html) for more.) * Present content specific to each user, such as their list of favorites. * Support social features, such as letting users "follow" one another, for example. @@ -9,7 +9,7 @@ In mobile applications, data about users is typically added by users themselves ## Creating users -A user entity represents an application user. Using API Services you can create, retrieve, update, delete, and query user entities. See User entity properties for a list of the system-defined properties for user entities. In addition, you can create user properties specific to your application. +A user entity represents an application user. Using API Services you can create, retrieve, update, delete, and query user entities. See [User entity properties](../rest-endpoints/api-doc.html#user) for a list of the system-defined properties for user entities. In addition, you can create user properties specific to your application. ### Request Syntax @@ -38,13 +38,13 @@ The username is mandatory and must be unique. Here's an example: "password" : "test1234" } -Although the password parameter is not mandatory, if you don't specify it, the user will not be able to log in using username and password credentials. If a password is not specified for the user, and you're an Admin, you can set a password for the user (see Setting a password). +Although the password parameter is not mandatory, if you don't specify it, the user will not be able to log in using username and password credentials. If a password is not specified for the user, and you're an Admin, you can set a password for the user (see [Changing a User Password](#changing-a-user-password)). __ Note__: The username can contain any combination of characters, including those that represent letters, numbers, and symbols. ### Example -__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details. +__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See [Authenticating users and application clients](../security-and-auth/authenticating-users-and-application-clients.html) for details. ### Request @@ -96,7 +96,7 @@ __Note__: Although not shown in the API examples below, you need to provide a va You can retrieve data about users through cURL or one of the SDKs. Each provides a way to filter the list of users by data associated with the user, such as username or UUID, or other properties in the user entity. -See User entity properties for a list of the system-defined properties for user entities. In addition, you can create user properties specific to your application. +See [User entity properties](../rest-endpoints/api-doc.html#user) for a list of the system-defined properties for user entities. In addition, you can create user properties specific to your application. ### Request Syntax @@ -116,7 +116,7 @@ uuid | org_id Organization UUID or organization name uuid | app_id Application UUID or application name user identifier User UUID, username, or email address. -The alias ``/users/me`` can be used in place of the current userâs uuid, username, or email address. Note: The ``/users/me`` endpoint is accessible only if you provide an access token with the request (see Authenticating users and application clients). If you make an anonymous ("guest") call, the system will not be able to determine which user to return as /users/me. +The alias ``/users/me`` can be used in place of the current userâs uuid, username, or email address. Note: The ``/users/me`` endpoint is accessible only if you provide an access token with the request (see [Authenticating users and application clients](../security-and-auth/authenticating-users-and-application-clients.html)). If you make an anonymous ("guest") call, the system will not be able to determine which user to return as ``/users/me``. __Note__: The username can contain any combination of characters, including those that represent letters, numbers, and symbols.
