HingX.org API Revision 2, November 30, 2012 Revision History Date Revision Number Comments August 21, 2012 1 Phase 1 API Specification November 30, 2012 2 Phase 2 API Specification Contents Preface .................................................................................................................................................................. 4 Calling Convention ..................................................................................................................................................... 4 Authentication and Authorization ............................................................................................................................. 4 User Functions ....................................................................................................................................................... 5 Login (GET, POST) ...................................................................................................................................................... 5 View (GET, POST) ....................................................................................................................................................... 5 Find (GET, POST) ........................................................................................................................................................ 6 Register (POST) .......................................................................................................................................................... 7 Edit (POST) ................................................................................................................................................................. 8 AddToGroup (POST) ................................................................................................................................................... 9 RemoveFromGroup (POST) ........................................................................................................................................ 9 Group Functions .................................................................................................................................................. 10 Create (POST) .......................................................................................................................................................... 10 View (GET, POST) ..................................................................................................................................................... 11 Edit (POST) ............................................................................................................................................................... 12 Find (GET, POST) ...................................................................................................................................................... 13 AssignRoleToMember (POST) .................................................................................................................................. 14 RemoveRoleFromMember (POST) ........................................................................................................................... 15 Resource Functions .............................................................................................................................................. 16 Create (POST) .......................................................................................................................................................... 16 Edit (POST) ............................................................................................................................................................... 19 GetDetails (GET, POST) ............................................................................................................................................ 22 Find (GET, POST) ...................................................................................................................................................... 23 AddToFolder (POST) ................................................................................................................................................ 26 RemoveFromFolder (POST) ...................................................................................................................................... 27 ChangeOwner (POST) .............................................................................................................................................. 27 Delete (POST)........................................................................................................................................................... 28 GetSecurity (GET, POST) .......................................................................................................................................... 28 SetSecurity (POST) ................................................................................................................................................... 29 CommunityFeedback (POST) ................................................................................................................................... 30 Field Functions ..................................................................................................................................................... 31 GetOntology (GET, POST) ........................................................................................................................................ 31 GetFieldsExt (GET, POST) ......................................................................................................................................... 31 Folder Functions .................................................................................................................................................. 32 List (GET, POST) ....................................................................................................................................................... 32 Create (POST) .......................................................................................................................................................... 33 Delete (DELETE) ....................................................................................................................................................... 34 Download (GET, POST) ............................................................................................................................................ 34 Move (POST) ............................................................................................................................................................ 37 Copy (POST) ............................................................................................................................................................. 38 Appendix 1 – Supported Country Names ............................................................................................................. 39 Appendix 2 – Supported Time Zones .................................................................................................................... 42 Preface Calling Convention The API is located at http://hingx.org/Api (or http://hingx.org/API) root. Each functional section (User, Group, Resource, etc.) is represented by another level under the API root (e.g. http://hingx.org/Api/User) and the corresponding function is another level below that (e.g. http://hingx.org/Api/User/Login). The API expects the input to be provided in the format understood by ASP.NET 4.0 MVC 3 framework, which is one of the following: 1. HTTP GET 2. HTTP POST with application/x-www-form-urlencoded encoding 3. HTTP POST with application/json encoding 4. HTTP PUT 5. HTTP DELETE The output of all API functions always uses application/json encoding. Depending on the specific function, the output is either one standard “result” object, or a collection of standard “result” objects. The standard “result” object is a data wrapper that in addition to the payload also provides the status of the operation. Standard “result” object Result := { Success: boolean, StatusCode: int, StatusDescription: string, Data: {}, } Field Example Description Success true A Boolean value that indicates success (true) or failure (false) of the operation. Examine the value of the StatusCode field to determine the exact nature of the failure. StatusCode 0 A numeric code indicating the final status of the operation. The set of possible return values varies from function to function. Some error codes are the same across all functions. Value of 0 (zero) is an indication of “success”; non-zero values are an indication of “failure”. StatusDescription OK A textual explanation of the StatusCode. Data The payload. Empty if the corresponding API function was unable to process the request. Authentication and Authorization Many API functions require a valid HingX.org user account to perform their operations. Other API functions take an optional parameter specifying the user account information, and depending on the provided credentials their output may change. User Functions In this section you will find functions that pertain to user accounts, user profile management and group membership. Also, user authentication function is described in the scope of this section. Login (GET, POST) Validates the input username/password pair and issues a token that may be used to call APIs where user authentication information is either required or optional.