Web services creation

This article describes how to create a new resource with the Web API.

Getting a template resource

To create a new resource, you need to provide valid values for all the mandatory properties of a resource. To ease this the Web API provides a URL that returns a template URL the defaults that have been configured via the class and representation dictionaries. You can retrieve this template resource with an HTTP GET request on the following URL:

http://myserver:myport/api1/x3/erp/MYENDPOINT/MYCLASS/$template?representation=MYREPR.$create

• myserver:myport is your server name and port number. For example localhost:8124 if the SAFE X3 web server is installed locally.
• MYENDPOINT is the name of your Sage X3 People endpoint.
• MYCLASS is the name of the class that you want to query. It may be a standard class like BPCUSTOMER or a custom class that you have implemented (see the class dictionaries documentation).
• MYREPR is the name of the representation that you want to query. It may be a standard representation like BPCUSTOMER or a custom one (see the representation dictionaries documentation).

Note MYREPR must be a representation for MYCLASS. Otherwise you will get an error. A future version of the Web API will allow you to pass only MYREPR but this version (api1) requires both parameters.

Filling the template

Once you have a template, you can set the values of your new resource into its properties.

Note: the template contains several keys prefixed by $. You do not need these keys to create a resource so you can safely delete them.

The previous step (getting a template) is optional. You can also create the JSON payload of the new resource from scratch, as long as you provide valid values for all the mandatory properties.

Creating the resource

http://myserver:myport/api1/x3/erp/MYENDPOINT/MYCLASS?representation=MYREPR.$create

Status code

If successful, the request will return an HTTP status of 201. The Location header of the response will contain the URL of the created resource.

Otherwise it will return an HTTP error status (4xx or 5xx).

JSON result

The POST request returns the state of the resource which has been created. This payload may be slightly different from the one you submitted because the server applied business rules defined in the class and representation before saving.

Testing interactively

As described in the overview, you can test interactively with a tool like Postman.

Links

• Web Services overview
• SData Create Operation
• SData JSON Responses