General API Usage Guidelines

From Creately Developer

Jump to: navigation, search

Request

  • All API methods served by Creately will be under the URL https://creately.com/api
  • All API request must be done over HTTPS
  • Almost all API calls can only be done via HTTPS POST. However some calls are allowed to be made both via GET and POST
  • Example request
URL: https://creately.com/api/document
POST Params: action=createdoc&name=NewDoc&diagramtype=uml-class

Response

  • All API calls will respond with either a XML, JASON style text or a multipart file.
  • API responses will be wrapped with the <creately-api-response> xml tag.
  • API calls will have a <success> tag to denote if the call was successfully executed.
  • When an API call is successful, the resulting data of the API call will be within the <creately-api-response> tag.
  • What is expected as result in each API call is defined in the respective API method documentation.
  • When an API call fails, error details will be sent in the response.
  • Example successful response
<creately-api-response>
 	<success>true</success>
	<doc-id>f4ne342d</doc-id>
	<link-to-document>http://creately.com/app?diagid=f4ne342d</link-to-document>
</creately-api-response>

Error

  • When an API call fails a <errorcode> tag will be sent in the response. The value of the tag will have valid error code from the API error list.
  • A <messsage> tag will contain a message that describes the error. These messages are listed in API error list.
  • For a third-party application that is using the Creately API, some messages are suitable for displaying to the user and some may not be. They should be handled accordingly to provide a good user experience.
  • Example API XML response with error:
<creately-api-response>
	<success>false</success>
	<errorcode>1103</errorcode>
	<message>The provided API Key is not permitted to perform any action on the requested user or user's data.</message>
</creately-api-response>
Personal tools