API Reference Manual

Transcription

1 FUJITSU Cloud Service K5 API Reference Manual Version.5 FUJITSU LIMITED

2 Preface Purpose of This Document This guide describes the specification of the API (Application Programming Interface) provided by the FUJITSU Cloud Service K5. You are recommended to also refer to the following related manuals: - K5 API User Guide - K5 Portal User Guide Compliance with Export Control Regulations When exporting this document or providing it to a third party, check the export control laws and regulations of your country and the U.S. and take necessary procedures. Notices - The contents of this manual are subject to change without notice. - The contents of this manual shall not be reproduced without express written permission from FUJITSU LIMITED. - FUJITSU LIMITED shall bear no responsibility for any claims of violation of a third party's patent or other rights arising from the use of the data described in this document. i

3 Document history Version Date Edited places Description. Oct 7, API Execution Errors Update error messages. 3.2 API Execution Errors.2 Dec.22, Access Rights by Role Add the section. List of API 2.3. Get Access Token Modifications corresponding to the new function Update user authentication information.3 May.5, Get Access Token Add explanation.4 Aug 30, Get Access Token Add explanation.5 Jan 9, Get Access Token Modify explanation ii

4 Table of Contents Chapter API Outline... List of API... 2 Access Rights by Role... 3 Glossary Chapter 2 Authentication API... 5 Request Headers... 6 API Execution Errors... 6 API Specification Get access token Chapter 3 User management API... 0 Request Headers... API Execution Errors... API Specification Create new user Change user information Change user password Delete user Update user authentication information... 9 iii

5 Chapter API Outline

6 List of API No. API Group API Method URL Description Authentication User management Get access Get token for API POST token m/api/paas/auth/token authentication. Create user POST Create a new user. /v/api/users Change information of Change user PUT the contractor or the information /v/api/users specified user. Change user Change password of the PUT password /v/api/userspassword specified user. 5 Delete user DELETE Update user 6 authentication PUT information Delete the specified /v/api/users/?login_id=username user. Update user authentication method /v/api/usersauthenticationmethod of the contractor or a user. API character encoding is UTF-8. 2

7 Access Rights by Role Each user of the K5 Portal is assigned a Role that controls the operations the user is authorized to perform on the K5 Portal. (Refer to the 'K5 Portal User Guide' for detail.) Also for the use of APIs, access rights are assigned by role as shown below. API group API name Authntication Get Access Token User Management Operation object Operation object Operation object Oneself USER Oneself Contractor USER Oneself Contractor USER Create New User X X X X X X Change User Information * * X X Change User Password X X X X X Delete User X X X X X X Update user authentication information K5 common service Roles USER Contractor Administrator Developer X X X X X : Permitted X: Not Permitted *:Permitted with restrictions (See [Change user information ] below.) By API name, the roles to which the executions are permitted are shown below. [Create New User] - The Contractor and Administrator can create a user except with the role of Contractor. [Change user information] - The Administrator and Developer can change the information of one s own, including password. - The information of the Contractor which can be changed by an Administrator is only its password. - The Contractor can change his/her own information, except its user status. - The Contractor and Administrator can change the information of USERs (Administrator / Developer ). [Change user password] - Regardless of role, a user can change one s own password. [Delete user] - The Contractor and Administrator can delete a user with a role except Contractor. [Update user authentication information] - All users can update his/her own user authentication method. 3

8 Glossary Term User User name Role Explanation Person (or system, service) who uses or manages a function Unique ID of a user Authorization granted to a person or a group. Role of a user determines which API that user can execute. Role code Unique ID of a role 4

9 2 Chapter 2 Authentication API 5

10 Request Headers Request headers for authentication API No. Header Name Required Header value Content-Type Yes application/json 2 X-FCX-Client-Cert *See note Client certificate mapped to the user *Note: Required, in cases where Certificate and Password authentication is used. API Execution Errors API execution error information is returned in HTTP response body under json format. No. Format Item Type Cardinality Description errorlevel string.. Error level 2 framework object.. Framework object 3 systemerrorcode string.. System error code JSON 4 business object.. Business object [Body] 5 businesserrorinfo string.. Error message 6 responseerrorcode string.. Response error code 7 embeddedstring string array.. Additional information "errorlevel": "888", "framework": "systemerrorcode": "", "business": "businesserrorinfo": "Cannot create token from the specified user information.", "responseerrorcode": "RCM30802", "embeddedstring": [ ] 6

11 List of response errors No. HTTP status Error Information Error message Error reason 400 Request parameter error Parameter is invalid. Specified parameter: XXX * XXX is the parameter name Cannot create token Cannot create token from the specified user information Server error Failed to create token (Internal Error). Request parameter error (empty parameter, invalid length, invalid format ) User information specified in the request is invalid Internal server error 7

12 API Specification 2.3. Get access token. Request Parameter definition No. Format Item Required Cardinality Min. length Max. length Restrictions Description auth Yes Object Authentication object 2 identity Yes Object Identity object 3 password Yes Object Password object 4 user Yes Object User object 5 contract_number Yes See Note(*) Contract number of authentication user 6 name Yes See Note(*) User name of authentication JSON user [Body] 7 password Yes See Note(*) Password of authentication 8 timezone No - - See Note(*) Timezone *case-insensitive user If no timezone, a timezone other than 'UTC', or an invalid timezone is specified, 'JST' is automatically set. (*): Upper/Lower case alphanumeric characters. For more details please refer to K5 Portal User Guide (..2 Essential Information for the use of the K5 Portal) input restrictions. "auth": "identity": "password": "user": "contract_number":"xxxxxxxx", "name":"user-name", "password":"user-password", "timezone":"utc" 8

13 2. Response HTTP STATUS:20 Response body: No. Format Item Cardinality Description 2 JSON [Body] token.. Token object expires_at.. Expiration of an access token. The expiration from the time of an initial issuance is 30 minutes later. Timezone : 'UTC' if 'UTC' is specified in 'timezone' of. Request. 'JST' if other than 'UTC'. Format : 3 scope.. Token scope 4 user.. User object YYYY-mm-ddTHH:MM:SS.SSSZ (if 'UTC') YYYY-mm-ddTHH:MM:SS (if 'JST') 5 contract_number.. Contract number of authentication user 6 name.. User name of authentication user "token": "expires_at":" t03:20:42", "scope":"paas", "user": "contract_number":"xxxxxxxx", "name":"user-name" 9

14 3 Chapter 3 User management API 0

15 Request Headers API execution error information is returned in HTTP response body under json format. No. Header Name Required Header value Token Yes Access token acquired by executing Get access token API 2 Content-Type Yes application/json API Execution Errors API execution error information is returned in HTTP response body under json format. No. Format Item Type Cardinality Description errorlevel string.. Error level 2 framework object.. Framework object 3 systemerrorcode string.. System error code 4 JSON business object.. Business object 5 [Body] businesserrorinfo string.. Business error information 6 responseerrorcode string.. Response error code 7 embeddedstring string array.. Error message "errorlevel": "888", "framework": "systemerrorcode": "", "business": "businesserrorinfo": "BECSA0003", "responseerrorcode": "RCS0000", "embeddedstring": [ "Internal Server Error" ]

16 List of response errors No. HTTP status 400 Request parameter error Error Information Error message Error reason * XXX is the parameter name Delete contractor error Password check error - Parameter is insufficient. Required parameter: XXX - Parameter is required. Character count of parameter is invalid. Specified parameter: XXX The format of parameter is invalid. Specified parameter: XXX Could not delete user because the target user is a contractor. Password is of invalid format or does not satisfy password policy. Please try again. Password cannot be changed again within 24 hours since the last change. Please try again after 24 hours. Failed to change password. The old password was invalid Invalid user status Cannot change user information because user status of the target user is invalid Invalid token The specified access token is not valid. Insufficient parameters Input parameter check error (digit number fault) Input parameter format error (other than digit number) Try to delete a contractor Violate password policy Try to change password again within 24 hours Previous password error Try to change information of user whose status is invalid Access token is not valid Authorization error Authorization Error. Action not authorized Change contractor status error Unauthorized to change information of the specified Try to change user status of a contractor user Not found The target information does not exist. Target information not found Exclusive error Operation conflicts with another one. Target information has already been changed by another process Internal Server Error Internal Server Error. Consistency error, or other server errors 2

17 API Specification 3.3. Create new user. Request Parameter definition No. Format Item Required Cardinality Min. length Max. length Restrictions login_id Yes See Note (**) 2 user_description No See Note (**) 3 mailaddress Yes Proper address format (*) 4 user_status Yes.. Invalid (0) / Valid () JSON 5 password Yes See Note (**) [Body] 6 language_code Yes role_code Yes Japanese (ja) / English (en) Administrator (00),Developer (0) 8 user_last_name Yes.. 64 See Note (**) Description User name of the user to be created User description of the user to be created address of the user to be created User status of the user to be created Password of the user to be created Language code of the user to be created Role code of the user to be created Last name of the user to be created First name of the user to be 9 user_first_name Yes.. 64 See Note (**) created (*): For the detail of address format, please refer to K5 Portal User Guide (..2 Essential Information for the use of the K5 Portal) input restrictions. (**):Upper/Lower case alphanumeric characters. For more details, please refer to K5 Portal User Guide (..2 Essential Information for the use of the K5 Portal) input restrictions. "login_id": "fujitsu23", "user_description": "User description", "mailaddress": "abc@xyz.com", "user_status": "", "password": "Abcdefgh ", "language_code": "ja", "role_code": "00", "user_last_name": "Smith", "user_first_name": "John" 3

18 3. Response HTTP STATUS:200 Response body: No. Format Item Cardinality Description login_id.. User name of the newly created user 2 user_description.. User description of the newly created user 3 mailaddress.. address of the newly created user 4 user_status.. User status of the newly created user 5 Invalid (0) / Valid () JSON language_code.. Language code of the newly created user [Body] Japanese (ja) / English (en) 6 authentication_method.. Authentication method * This API returns fixed value: Password authentication (0) 7 user_last_name.. Last name of the newly created user 8 user_first_name.. First name of the newly created user "login_id": "fujitsu23", "user_description": "User description.", "mailaddress": "abc@xyz.com", "user_status": "", "language_code": "ja", "authentication_method ": "0", "user_last_name": "Smith", "user_first_name": "John" 4

19 3.3.2 Change user information. Request Parameter definition No. Format Item Required Cardinality Min. 2 JSON [Body] length Max. length Restrictions login_id Yes See Note (**) mailaddress No (*) Proper address format (***) Description User name of the target user New address 3 user_description No (*) See Note (**) New user description 4 5 language_code No (*) user_status No (*) 0.. Japanese (ja) / English (en) Invalid (0) / Valid () * Trying to change user status of a contractor will result in error New language code New user status 6 password No (*) See Note(**) New password 7 user_last_name No (*) See Note(**) New user Last name 8 user_first_name No (*) See Note (**) New user First name (*): At least one parameter must be set. Upper / Lower case alphanumeric characters. (**): Upper / Lower case alphanumeric characters. For more details, please refer to K5 Portal User Guide (..2 Essential Information for the use of the K5 Portal) input restrictions. (***): For the detail of address format, please refer to K5 Portal User Guide (..2 Essential Information for the use of the K5 Portal) input restrictions. "login_id": "fujitsu23", "mailaddress": "abc@xyz.com", "user_description": "User description.", "language_code": "ja", "user_status": "", "password":"abcdefgh ", "user_last_name": "Smith", "user_first_name": "John" 5

20 2. Response HTTP STATUS:200 Response body: No. Format Item Cardinality Description login_id.. User name of the target user language_code.. New language code 2 3 user_status.. New user status 4 mailaddress.. New address 5 JSON user_description.. New user description 6 [Body] user_last_name.. New user Last name 7 user_first_name.. New user First name 8 accesstoken_destruction_information_list.. User information whose token was cancelled. 9 customer_group_id.. Group ID to which the user belongs to. 0 login_id.. Login ID of the user. "login_id": "fujitsu23", "language_code": "ja", "user_status": "", "mailaddress": "abc@xyz.com", "user_description": "User description.", "user_last_name": "Smith", "user_first_name": "John" "accesstoken_destruction_information_list":[ "customer_group_id":"hvlgxxym", login_id":" fujitsu23" ] 6

21 3.3.3 Change user password. Request Parameter definition No. Format Item Required Cardinality Min. Max. Restrictions Description length length User name of the target login_id Yes See Note (*) user JSON 2 [Body] after_password Yes See Note (*) New password 3 before_password Yes See Note (*) Old password (*): Upper / Lower case alphanumeric characters. For more details, please refer to K5 Portal User Guide (..2 Essential Information for the use of the K5 Portal) input restrictions. "login_id": "fujitsu23", "after_password":"newpassword ", "before_password":"abcdefgh " 2. Response HTTP STATUS:200 Response body: No. Format Item Cardinality Description accesstoken_destruction_information_list.. User information whose token was JSON cancelled. 2 [BODY] customer_group_id.. Group ID to which the user belongs to. 3 login_id.. Login ID of the user. "accesstoken_destruction_information_list":[ "customer_group_id":"hvlgxxym", login_id":" fujitsu23" ] 7

22 3.3.4 Delete user. Request Parameter definition No. Format Item Required Cardinality Min. Max. Restrictions Description length length URL query parameter login_id Yes See Note (*) User name of the user to be deleted (*): Upper / Lower case alphanumeric characters. For more details, please refer to K5 Portal User Guide (..2 Essential Information for the use of the K5 Portal) input restrictions. /API/v/api/users/?login_id= fujitsu23 2. Response HTTP STATUS:200 Response body: No. Format Item Cardinality Description accesstoken_destruction_information_list.. User information whose token was JSON cancelled. 2 [BODY] customer_group_id.. Group ID to which the user belongs to. 3 login_id.. Login ID of the user. "accesstoken_destruction_information_list":[ "customer_group_id":"hvlgxxym", login_id":" fujitsu23" ] 8

23 3.3.5 Update user authentication information. Request Parameter definition No. Format Item Required Cardinality Min. Max. Restrictions Description length length login_id Yes See Note (*) User name of the target user 2 JSON [Body] Authentication method for the user authentication_method Yes.. See Note (*) 0: Authentication by a password : Authentication by a certificate & password (*): Upper / Lower case alphanumeric characters. For more details, please refer to K5 Portal User Guide "login_id": "fujitsu23", "authentication_method ":"", 9

24 2. Response HTTP STATUS:200 Response body: No. Format Item Cardinality Description JSON [Body] authentication_method.. Authentication method for the user. 0: Authentication by a password : Authentication by a certificate & password accesstoken_destruction_information_list.. User information whose token is to be canceled. customer_group_id.. Contract number of the user whose token is to be canceled. login_id.. Login ID of the user whose token is to be canceled. "authentication_method":""," "accesstoken_destruction_information_list":[ "customer_group_id":"hvlgxxym", "login_id":" fujitsu23" ] 20

25 FUJITSU Cloud Service K5 API Reference Manual Version.5 Issued January 208 All Rights Reserved, Copyright FUJITSU LIMITED 2