iControl® REST API User Guide Version 14.1 | Contents | ii Contents REST.......................................................................................................................... 5 About Representational State Transfer................................................................................................................ 5 Important changes in iControl REST API...........................................................................................................5 Overview: URI format and structure................................................................................................................. 10 About reserved ASCII characters...........................................................................................................11 About REST resource identifiers........................................................................................................... 11 About HTTP method semantics......................................................................................................................... 11 About JSON request and response semantics....................................................................................................12 About additional iControl REST properties...........................................................................................14 About null values and properties........................................................................................................... 16 About reserved property names..............................................................................................................17 About property name format differences............................................................................................... 17 About JSON formats and encodings......................................................................................................17 About API versions............................................................................................................................................ 17 Password change in iControl REST...................................................................................................................18 Changing a password by using an iControl REST request....................................................................18 About iControl and authentication for user accounts........................................................................................ 18 Requesting a token for iControl REST authentication.......................................................................... 18 Overview: Fundamentals of Cross-Origin Resource Sharing............................................................................19 Cross-Origin Resource Sharing request headers....................................................................................20 Cross-Origin Resource Sharing response headers................................................................................. 20 About external authentication providers with iControl REST...........................................................................20 GET Requests..........................................................................................................21 Discovering modules and components...............................................................................................................21 About paging properties......................................................................................................................... 24 About query parameters......................................................................................................................... 24 Paging through large collections............................................................................................................26 About sub-collection expansion............................................................................................................. 27 Returning resources from an administrative partition............................................................................30 Use iControl REST to obtain statistical output..................................................................................... 31 POST and PUT requests........................................................................................34 About JSON format for POST and PUT...........................................................................................................34 Creating a new resource with iControl.............................................................................................................. 34 Modifying a resource with PATCH.......................................................................................................35 About read only properties.....................................................................................................................36 Adding or modifying in a specific partition.......................................................................................... 36 Deleting Access Policy Manager resources........................................................................................... 38 Partitions..................................................................................................................38 About administrative partitions.......................................................................................................................... 38 Creating folders.......................................................................................................................................39 Deleting an administrative partition.......................................................................................................41 | Contents | iii Transactions.............................................................................................................41 About the iControl REST transaction model.....................................................................................................41 About iControl REST transaction phases.............................................................................................. 41 About transaction validation...................................................................................................................42 Additional transaction properties............................................................................................................42 Creating an iControl REST transaction................................................................................................. 43 Modifying a transaction..........................................................................................................................43 Committing an iControl REST transaction............................................................................................44 About iControl REST asynchronous tasks.........................................................................................................45 Asynchronous task endpoints................................................................................................................. 45 Using an asynchronous task................................................................................................................... 46 Commands............................................................................................................... 47 About other tmsh global commands.................................................................................................................. 47 Using the cp command...........................................................................................................................48 Using the generate command................................................................................................................. 48 Using the install command.....................................................................................................................49 Using iControl REST to create a key.................................................................................................... 49 Using the load command........................................................................................................................50 Using the mv command......................................................................................................................... 50 Using the publish command...................................................................................................................51 Using the reboot command.................................................................................................................... 51 Using the restart command.....................................................................................................................51 Using the reset-stats command...............................................................................................................52 Using the run command......................................................................................................................... 52 Using the save command....................................................................................................................... 52 Using the send-mail command...............................................................................................................53 Using the start command........................................................................................................................54