Transcription
Sage CRM 2016 R1RESTful APIGetting StartedRevision: CLO-RESTAPI-ENG-161-1.0Updated: September 2015
Copyright 2015 Sage Technologies Limited, publisher of this work. All rights reserved.No part of this documentation may be copied, photocopied, reproduced, translated, microfilmed, orotherwise duplicated on any medium without prior written consent of Sage Technologies Limited.Use of the software programs described herein and this documentation is subject to the End UserLicence Agreement enclosed in the software package, or accepted during system sign-up.Sage and the Sage logo are registered trademarks or trademarks of The Sage Group PLC. Allother marks are trademarks or registered trademarks of their respective owners.Sage CRM 2016 R1 RESTful API - Getting StartedPage 2 of 19
ContentsAbout Sage CRM RESTful APIRequired permissionsGetting helpUseful toolsMore information45556Supported entities7HTTP methods and request URLs8Viewing entity properties10Creating an entity record12Retrieving entity recordsRetrieving all entity records of the same typeRetrieving a single entity record131314Updating an entity record15Deleting an entity record16Retrieving details about your environment17Status and error codes19Sage CRM 2016 R1 RESTful API - Getting StartedPage 3 of 19
About Sage CRM RESTful APIThe Sage CRM RESTful API enables developers and system administrators to programmaticallymanipulate entity records in Sage CRM. REST stands for Representational State Transfer and is asoftware architecture style consisting of guidelines and best practices for creating scalable webservices.Sage CRM RESTful APIGETPOST JSON payloadPATCHDELETESage CRMHTTP requestHTTPSJSON responseDeveloperEntity recordsWith the Sage CRM RESTful API, you can programmatically create, read, update, and delete entityrecords in your Sage CRM system using HTTP requests and standard HTTP methods such asGET, POST, PATCH, and DELETE. To ensure security, the RESTful API is served over secureHTTP (HTTPS) only.The RESTful API provides access to Sage CRM entities via URL paths. To use the RESTful API,your application must make an HTTP request in a specific format and parse the response. TheRESTful API always returns JSON responses.The RESTful API is based on open standards, and therefore you can use virtually any webdevelopment language to work with entities in Sage CRM via this API.Before you start using the RESTful API, we recommend that you familiarize yourself with SData.SData is a web toolkit promoting the development of REST-orientated services and theirconsumption in Sage CRM. It consists of a small, standards-based core (HTTP, ATOM, and JSON)and a set of optional mechanisms solving common implementation challenges in a consistentmanner. For more information, see the SData Specification.For more information about the entities you can work with via the RESTful API, see Supportedentities.Sage CRM 2016 R1 RESTful API - Getting StartedPage 4 of 19
Required permissionsTo use the Sage CRM RESTful API, you must be a system administrator in Sage CRM.Getting helpSage CRM has a built-in interactive help system providing information on how to manipulateentities via the RESTful API.In the RESTful API help, you can view a list of entities you can work with, learn how to form anHTTP request to manipulate an entity record of a particular type, view the format of JSON payloadsyou need to use and JSON responses returned by Sage CRM, and actually perform CRUDoperations on your entity records.The RESTful API help is generated dynamically for your Sage CRM environment. For this reason,to use the help you need to be logged in to Sage CRM as a system administrator.To view the RESTful API Help1. Log in to Sage CRM as a system administrator.2. In the top right corner of the Sage CRM window, click Your Profile Administration.3. In the left pane, click Manage My Account, and then click the External Access tab.4. Click View RESTful API Help.The page that opens lists the entities you can work with via the Sage CRM RESTful API. If thepage is blank, click Refresh to get a list of supported entities.For more information about an entity, click the entity entry on the RESTful API Help page.Please note that of all core entities only Company and Person are currently supported throughthe RESTful API. Although other core entities may be present in the list, you cannot work withthem through the RESTful API.Warning: Use the Try it out! button provided in the RESTful API Help with caution. Thisbutton sends the HTTP request and can modify your data in Sage CRM.Please note that although the RESTful API Help shows the format of curlrequests, these requests are currently not supported. Use curl at your own risk.Useful toolsWhen working with the Sage CRM RESTful API, you may find the following tools useful: A REST client. Allows you to create and test custom HTTP requests and view JSON payloadsand responses in a human-readable format. For example, you may want to use one of thefollowing: Advanced REST Client for Google Chrome Simple REST Client for Opera RESTClient for Mozilla FirefoxTo find out more about the HTTP methods and request URLs you can use in your Sage CRMenvironment, see HTTP methods and request URLs. A web browser add-on that makes JSON readable. Shows JSON text (payloads andresponses) in your web browser in a human-readable format. For example, you can use theJSONView add-on for Google Chrome or Mozilla Firefox.Sage CRM 2016 R1 RESTful API - Getting StartedPage 5 of 19
More informationFor in-depth information about the Sage CRM RESTful API and the SData toolkit, please refer tothe following: SData Specification Sage CRM's RESTful API: SData for Cloud and On-Premise (in 10 parts). This is a series ofarticles posted by Jeff Richards on the Sage CRM Partner Community.Sage CRM 2016 R1 RESTful API - Getting StartedPage 6 of 19
Supported entitiesThe list of entities you can work with via the RESTful API is specific to your Sage CRMenvironment. You can view that list either in the RESTful API Help (see Getting help) or bycompleting the steps below.In Sage CRM, you can use the RESTful API to work with the following: All custom entities Company core entity Person core entityTo view a list of entities supported via the RESTful API1. Log in to Sage CRM as a system administrator.2. Go to Your Profile Administration Manage My Account External Access.3. Under RESTful API, click View supported entities (SData prototypes). You may beprompted to enter your Sage CRM credentials.For best results, we recommend that you install a web browser add-on that shows JSONresponses in a human-readable format (see Useful tools).A page similar to the following opens:Under the resources element on this page, you can view a list of all entities supported viathe RESTful API in your environment.Note:Please note that of all core entities only Company and Person are currently supportedvia the RESTful API. Although other core entities may be present in the list, you cannotwork with them via the RESTful API.Each listed entity has the following elements: title. Shows entity description. resourceKind. Shows entity name. url. Provides a URL you can use to view entity properties and the HTTP methods theentity supports.Sage CRM 2016 R1 RESTful API - Getting StartedPage 7 of 19
HTTP methods and request URLsTo manipulate entities in Sage CRM via the RESTful API, you need to make HTTP requests byusing URLs that are specific to your Sage CRM environment. The URL you need to use dependson the type of the entity record you want to manipulate and the action you want to perform. Fordetailed information, refer to the RESTful API Help (see Getting help).To view HTTP methods and request URLs for an entity1. Log in to Sage CRM as a system administrator.2. Go to Your Profile Administration Manage My Account External Access.3. Under RESTful API, click View supported entities (SData prototypes). You may beprompted to enter your Sage CRM credentials.For best results, we recommend that you install a web browser add-on that shows JSONresponses in a human-readable format (see Useful tools).A page similar to the following opens:4. Under the resources element, locate the entity you want to work with, and then click theURL in the corresponding url element.To locate the entity by its name, you can use the resourceKind element.5. On the page that opens, scroll down to the bottom to locate the links element that lookssimilar to the following:Sage CRM 2016 R1 RESTful API - Getting StartedPage 8 of 19
The links element lists the standard HTTP methods you can use on the entity, such asPOST, PATCH, DELETE, and GET.6. Use the following elements to locate the HTTP method you want to use: method. Shows the HTTP method name (POST, PATCH, DELETE, or GET). url. Provides the URL you can use to invoke the corresponding HTTP method on theentity records of this type.In the URL, replace the { key} placeholder with the unique ID of the entity record youwant to work with. For more information on how to find out the unique ID of an entityrecord, see Retrieving entity records.Sage CRM 2016 R1 RESTful API - Getting StartedPage 9 of 19
Viewing entity propertiesEach entity in Sage CRM has a number of properties. These properties define the characteristicsand behavior of the entity. An entity property can be exposed as a field on the Sage CRM userinterface (UI).In turn, each entity property has its own properties that define the characteristics and behavior ofthe corresponding field on the Sage CRM UI.To view all properties of an entity by using the RESTful API1. Log in to Sage CRM as a system administrator.2. Go to Your Profile Administration Manage My Account External Access.3. Under RESTful API, click View supported entities (SData prototypes). You may beprompted to enter your Sage CRM credentials.For best results, we recommend that you install a web browser add-on that shows JSONresponses in a human-readable format (see Useful tools).A page similar to the following opens:This page lists all entity types (also known as SData prototypes) existing in Sage CRM.4. Under the resources element, locate the entity whose properties you want to view, and thenclick the URL in the corresponding url element.To locate the entity by its name, you can use the resourceKind element.The page that opens lists all properties of the entity, for example:Sage CRM 2016 R1 RESTful API - Getting StartedPage 10 of 19
Under the properties element, you can view the entity properties. In the example above,the Company entity has the Comp TimeStamp property. In turn, this entity property has thefollowing field properties: title. Shows field description. type. Shows field type. For more information, see SData JSON Types in the SDataSpecification. isMandatory. Shows whether or not the property is mandatory, that is, must be populatedwhen creating a new entity record of this type. isHidden. Shows whether or not the property is hidden on the Sage CRM user interface. isReadOnly. Shows whether the property value is read-only or writable.You can modify the request URL in step 4 of this procedure to return only specific properties ofthe entity. For that, add the following syntax to the URL:?select Properties separated by comma To modify and test the URL, you can use one of the REST clients listed in Useful tools.ExampleGET H1RC9j/sagecrm2/-/ prototypes/Company?select Comp TimeStamp,Comp CompanyIdThis example returns the Comp TimeStamp and Comp CompanyId properties of theCompany entity. In this case, the JSON response will look similar to the following:Sage CRM 2016 R1 RESTful API - Getting StartedPage 11 of 19
Creating an entity recordYou can create a new entity record through the RESTful API by using the HTTP POST request. Tofind out what HTTP request URL you need to use to create an entity record of particular type, seeHTTP methods and request URLs.When creating a new entity record in Sage CRM, please consider the following: Populate all mandatory properties of the entity record. Each entity in Sage CRM has anumber of properties that must be populated with values when you create a new record of thattype. These properties are called mandatory. For information on how to determine which entityproperties are mandatory, see Viewing entity properties. Make sure the properties you want to populate are writable. Some entity record propertiesmay be read-only. If so, your attempt to populate these properties will fail. For information onhow to determine which entity properties are writable, see Viewing entity properties. Note the returned unique ID of the entity record. When an entity record is createdsuccessfully, the JSON response you receive includes the unique ID (key) of the newly createdrecord. You can use that ID to link the newly created entity record to another entity. Forexamples, see article Sage CRM's RESTful API: SData for Cloud and On-Premise (Part 10 of10) posted on the Sage CRM Partner Community.ExamplePOST H1RC9j/sagecrm2//Conference{"Conf Name": "My conference""Conf Topi": "Sample conference topic"}In this example, the POST request creates a new Conference entity record. The JSON payloadincluded in the request specifies the name and topic for the Conference record being created. Notethat in your case the HTTP request URL will be different from the one in the example.For more information, refer to the RESTful API Help (see Getting help).Sage CRM 2016 R1 RESTful API - Getting StartedPage 12 of 19
Retrieving entity recordsYou can use the RESTful API to retrieve all entity records of the same type existing in Sage CRM.In fact, this is the first action we'd recommend you to perform when you start using the RESTfulAPI.By retrieving all entity records you get complete information about the properties of each entityrecord, including the unique ID also known as key. Knowing the unique ID of an entity recordenables you to manipulate that record through the RESTful API, that is, retrieve, update, or deletethe record.Retrieving all entity records of the sametypeTo retrieve all entity records that belong to the same type, you need to use the HTTP GET requestthat doesn't include the unique ID of an entity record. For more information on the HTTP requestURLs, see HTTP methods and request URLs.ExampleGET H1RC9j/sagecrm2//CompanyIn this example, the GET request retrieves all Company entity records existing in Sage CRM. Notethat in your case the HTTP request URL will be different from the one in the example.The returned JSON response looks similar to the following:This JSON response has the following elements: totalResults. Shows the total number of Company records existing in Sage CRM (30 in thiscase). resources. Contains information about each Company record existing in Sage CRM. In thisexample, the resources element has the following subelements:Sage CRM 2016 R1 RESTful API - Getting StartedPage 13 of 19
key. Shows the unique ID of the record. You can use this ID to invoke HTTP methods onthis record. title. Shows the name of the record. url. Shows the base URL you can use to invoke HTTP methods on the record.Other subelements (such as Comp CompanyId, Comp WorkflowID,Comp intlastsyncdate, and so on) show the values of the record fields provided on theSage CRM user interface.For more information, refer to the RESTful API Help (see Getting help).Retrieving a single entity recordTo retrieve an entity record of your choice through the RESTful API, you need to use the HTTPGET request that specifies that record by its unique ID. To find out the unique ID of the record, youneed to retrieve all entity records of that type. For more information, see Retrieving all entityrecords of the same type.ExampleGET H1RC9j/sagecrm2//Company('28')In this example, the GET request retrieves the Company record whose unique ID is 28. Note that inyour case the HTTP request URL will be different from the one in the example.The structure of the JSON response you receive when retrieving a single entity record will beidentical to the one described in Retrieving all entity records. For more information, refer to theRESTful API Help (see Getting help).Tip:You can use additional parameters in your GET request URL to search for, filter, andsort entity records.For more information about these additional parameters, see Query Parameters in theSData Specification.Sage CRM 2016 R1 RESTful API - Getting StartedPage 14 of 19
Updating an entity recordYou can use the RESTful API to selectively update properties of an existing entity record in SageCRM. To update an entity record, you can use the HTTP PATCH request that specifies the entityrecord by its unique ID. Alternatively, you can use the HTTP POST request that includes theunique ID of the entity record you want to update.We recommend that you ensure that the entity record properties you want to update are writable.For information on how to determine which entity properties are writable, see Viewing entityproperties.To find out the unique ID of a particular entity record, you need to retrieve all entity records of thattype. For more information, see Retrieving all entity records of the same type.To find out what HTTP request URL you need to use to update an entity record of a particular type,see HTTP methods and request URLs.Example 1: Using a PATCH requestPATCH H1RC9j/sagecrm2//Conference('28'){"Conf Topi": "New conference topic"}In this example, the PATCH request updates the topic of the Conference entity record whoseunique ID is 28. The JSON payload included in the request specifies the new conference topic,which is New conference topic. Note that in your case the HTTP request URL will be different fromthe one in the example.For more information, refer to the RESTful API Help (see Getting help).Example 2: Using a POST requestPOST H1RC9j/sagecrm2//Conference('4'){"Conf Description": "New conference description"}In this example, the POST request updates the description of the Conference entity record whoseunique ID is 4. If you omit the unique ID of the entity record, your POST request will create a newConference entity record. Note that in your case the HTTP request URL will be different from theone in the example.For more information, refer to the RESTful API Help (see Getting help).Sage CRM 2016 R1 RESTful API - Getting StartedPage 15 of 19
Deleting an entity recordYou can use the RESTful API to selectively delete entity records in Sage CRM. To delete an entityrecord, you need to use the HTTP DELETE request that specifies the entity record you want todelete by its unique ID.When you delete an entity record, it is permanently removed from Sage CRM and cannot berestored.ExampleDELETE H1RC9j/sagecrm2/-/Conference('28')In this example, the DELETE request permanently deletes the Conference entity record whoseunique ID is 28. Note that in your case the HTTP request URL will be different from the one in theexample.For more information, refer to the RESTful API Help (see Getting help).Sage CRM 2016 R1 RESTful API - Getting StartedPage 16 of 19
Retrieving details about yourenvironmentYou can use the RESTful API to retrieve information about your Sage CRM environment, namely: Web Services connection string Web Services WSDL file SData 2.0 URL SData 1.0 URL Sage CRM domain, edition, and versionTo retrieve this information, send an HTTP GET request by using the appropriate URL for yourlocation: In North America: https://cloud.na.sagecrm.com/getcrmurls In the European Union: https://cloud.eu.sagecrm.com/getcrmurlsYou will need to authenticate against Sage CRM using basic authorization. Your Sage CRM username and password must be encoded using Base64 and supplied in the HTTP GET requestheadings using the following syntax:Authorization: Basic UserName : Password Where UserName : Password are the credentials of a Sage CRM system administratoraccount encoded in Base64. To encode your credentials, you can use a free online service, suchas www.base64encode.org.Below is a sample HTTP GET request that retrieves information about Sage CRM environment:If your request was successful, you receive a JSON response similar to the following:Sage CRM 2016 R1 RESTful API - Getting StartedPage 17 of 19
This response has the following elements: installName. Shows the Sage CRM install name. wsdlUrl. Shows the URL at which you can access the Web Services WSDL file. wsUrlConnection. Shows the Web Services connection string. sDataUrl. Shows SData 1.0 URL. sData2Url. Shows SData 2.0 URL. edition. Shows the Sage CRM edition. domain. Shows the Sage CRM domain. version. Shows the Sage CRM version. userWebServicesEnabled. Shows whether Web Services are enabled for the user accountwith which you access Sage CRM.Sage CRM 2016 R1 RESTful API - Getting StartedPage 18 of 19
Status and error codesThe RESTful API returns standard HTTP response status codes to indicate whether the actionrequested by the client was a success.Below are the most common status and error codes you may receive when working with theRESTful API:HTTP status codeDescription200 OKThe request made by the client has succeeded.201 CreatedThe resource has been successfully created on the server.400 Bad RequestThe request syntax is incorrect.401 UnauthorizedCan indicate one of the following: The request does not include the required authorization headerfield. Authorization has failed using the credentials provided in theauthorization header field.403 ForbiddenThe request syntax was correct, but the server is refusing to fulfillthe request.404 Not FoundThe requested resource was not found.500 Internal Server ErrorAn internal server error has occurred.503 Service UnavailableThe requested service is temporarily unavailable.For detailed information about HTTP error and status codes, see the following: Status Code Definitions posted on the World Wide Web Consortium (W3C) website. Error Payload in the SData Specificaton.Sage CRM 2016 R1 RESTful API - Getting StartedPage 19 of 19
1. Log in to Sage CRM as a system administrator. 2. In the top right corner of the Sage CRM window, click Your Profile Administration. 3. In the left pane, click Manage My Account, and then click the External Accesstab. 4. Click View RESTful API Help. The page that opens lists the entities you can work with via the Sage CRM RESTful API.
