Raw REST examples

These REST examples demonstrate the data that is sent when you make a request.

Authenticate

You can make authentication requests with or without cookies. If you use the AP Essentials API SDK, you should use cookies for authentication. The SDK does not support cookie-less authentication. Cookie-less authentication is only available for uncommon cases where the AP Essentials API SDK is not used and cookie-less authentication is required.

Authenticate with a cookie

POST https://services.readsoftonline.com/authentication/rest/authenticate HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Encoding: gzip,deflate
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Content-Length: 73
Connection: Close

{"UserName":"myuser","Password":"mypassword","AuthenticationType":0}

Authenticate without a cookie

If you use the AP Essentials API SDK, you should use cookies for authentication. The SDK does not support cookie-less authentication. Cookie-less authentication is only available for uncommon cases where the AP Essentials API SDK is not used and cookie-less authentication is required.

When you successfully authenticate without a cookie, the response includes an authentication token that is valid for 30 minutes. After 30 minutes, the client must call the Authenticate API endpoint again to receive a new token.

The following C# code demonstrates how to authenticate without using cookies and without using the API SDK.

class Program
{
  private static readonly Uri AuthUri =
      new Uri("https://services.readsoftonline.com/authentication/rest/authenticate");

  private static readonly Uri CurrentUserUri =
      new Uri("https://services.readsoftonline.com/users/rest/currentuser");

  private static string ApiKey = "11111111-2222-3333-4444-555555555555";

  private static void Main(string[] args)
  {
    Authenticate();
  }

  private static void Authenticate()
  {
    var loginRequest = (HttpWebRequest)WebRequest.Create(AuthUri);

    loginRequest.Accept = "application/xml";
    loginRequest.ContentType = "application/xml";
    loginRequest.Headers.Add("x-rs-key", ApiKey);
    loginRequest.Method = "POST";

    using (var request = loginRequest.GetRequestStream())
    using (var sr = new StreamWriter(request, Encoding.UTF8))
    {
      sr.Write("<AuthenticationCredentials>");
      sr.Write("<UserName>account_name</UserName>");
      sr.Write("<Password>account_password</Password>");
      sr.Write("<AuthenticationType>SetBodyToken</AuthenticationType>");
      sr.Write("</AuthenticationCredentials>");
    }

    string authenticationToken;

    using (var response = loginRequest.GetResponse())
    using (var responseStream = response.GetResponseStream())
    using (var streamReader = new StreamReader(responseStream, Encoding.UTF8))
    {
      var body = streamReader.ReadToEnd();

      var xmlDocument = new XmlDocument { XmlResolver = null };
      xmlDocument.LoadXml(body);

      authenticationToken = xmlDocument.SelectSingleNode("/AuthenticationResult/Token").InnerText;
    }

    var getCurrentUserRequest = (HttpWebRequest)WebRequest.Create(CurrentUserUri);
    getCurrentUserRequest.Accept = "application/xml";
    getCurrentUserRequest.ContentType = "application/xml";
    getCurrentUserRequest.Headers.Add("x-rs-key", ApiKey);
    getCurrentUserRequest.Headers.Add("Authorization", $"ApsToken Value=\"{authenticationToken}\"");
    getCurrentUserRequest.Method = "GET";

    using (var response = getCurrentUserRequest.GetResponse())
    using (var responseStream = response.GetResponseStream())
    using (var streamReader = new StreamReader(responseStream, Encoding.UTF8))
    {
      var body = streamReader.ReadToEnd();

      var xmlDocument = new XmlDocument { XmlResolver = null };
      xmlDocument.LoadXml(body);

      var fullName = xmlDocument.SelectSingleNode("/User2/FullName").InnerText;

      Console.WriteLine($"Hello {fullName}");
    }
  }
}

The code above produces this authentication request:

POST https://services.readsoftonline.com/authentication/rest/authenticate HTTP/1.1
Accept: application/xml
Content-Type: application/xml
x-rs-key: 11111111-2222-3333-4444-555555555555

<AuthenticationCredentials>
  <UserName>account_name</UserName>
  <Password>account_password</Password>
  <AuthenticationType>SetBodyToken</AuthenticationType>
</AuthenticationCredentials>

A successful response to the request above would look like this:

<AuthenticationResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Status>Success</Status>
  <RedirectUri i:nil="true"/>
  <Challange i:nil="true"/>
  <ClientDeviceSecret i:nil="true"/>
  <Token>secret-token</Token>
</AuthenticationResult>

After a successful authentication without a cookie, a request to get the current user would look like this:

GET https://services.readsoftonline.com/users/rest/currentuser HTTP/1.1
Accept: application/xml
Content-Type: application/xml
x-rs-key: 11111111-2222-3333-4444-555555555555
Authorization: ApsToken Value="secret-token"

Get current user response (body):

<User2 xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Id>22222222222222222222222222222222</Id>
  <OrganizationId>11111111111111111111111111111111</OrganizationId>
  <UserName>account_name</UserName>
  ....
</User2>

GetDocumentOutputData

POST https://services.readsoftonline.com/documents/rest/file/77d38d515ae6447ea2ef0465bd59c2d6/data HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Encoding: gzip,deflate
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=33B1C66101611E8FBA7E38DFF2BC2C90288A09C9472963DDFB3EB8164D2BE1068CCFBD0C99A2A27D3B4C4D71B68061D1538986597BFFE7B822F95B34F17C712367D47B7CE683F557EC7CFDAA5906E70600757B7EF1DEC8CA1F3723B59894F878CCB4EF292E0F1319D52FE80B21FC180EA2B90F91C7C1CD4FBF0A5732DA6CE1229EBED0E05CD5A0D53DCBC86A6C5D35880DC182A3CD249A378FFE1060215BF969EA6C8D8ADEDEAA4DF530086EC87B5EC758B4353377BAFA4BAD4FC18C4AC4B55BD1475B5F7F000AB7EC803677BC9A42A9FB9388155481478420ED850E57B05A7A; 
x-rs-host=somepartner.readsoftonline.com
Content-Length: 2
Connection: Close
[]

GetDocumentOutputImage

GET https://services.readsoftonline.com/documents/rest/file/ccc5cae1ec0a47b89fb6fc3afee92d73/image HTTP/1.1
Accept: */*
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=127E5FA6CCB41269F4B814E6610B57BB3A9540188DDD424A26566FDAF9B8254D0A3B8A7257054383B6946BD17695CD041570CF29ED81A5F7508797D4E43307219B497EE647E7963C894F21F05AAE1081F373CF70F07B633E66C9B415C3C40B892CC2E074C131B80F4C524E93680963C569E0AA782E1B167210A47E72B0ACC682E2D1584DCC3568E3BBCE4DBC272FC2C0428DAC177B723CC56E6213F8E3E1AF7518A7E1664CBCBE7F786F3343CCF05CE939638D68938F13584153FB060E83C4A834D54D31CB7BE7D568D92029EF6190DAF8168D48C366300B33E6DE8611529DA8; 
x-rs-host=somepartner.readsoftonline.com
Accept-Encoding: gzip, deflate
Connection: Close

GetOutputDocuments

GET https://services.readsoftonline.com/documents/rest/customers/outputdocumentsbycurrentcustomer HTTP/1.1
Accept: */*
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=127E5FA6CCB41269F4B814E6610B57BB3A9540188DDD424A26566FDAF9B8254D0A3B8A7257054383B6946BD17695CD041570CF29ED81A5F7508797D4E43307219B497EE647E7963C894F21F05AAE1081F373CF70F07B633E66C9B415C3C40B892CC2E074C131B80F4C524E93680963C569E0AA782E1B167210A47E72B0ACC682E2D1584DCC3568E3BBCE4DBC272FC2C0428DAC177B723CC56E6213F8E3E1AF7518A7E1664CBCBE7F786F3343CCF05CE939638D68938F13584153FB060E83C4A834D54D31CB7BE7D568D92029EF6190DAF8168D48C366300B33E6DE8611529DA8; 
x-rs-host=somepartner.readsoftonline.com
Accept-Encoding: gzip, deflate
Connection: Close

UploadImage

POST https://services.readsoftonline.com/files/rest/image2?filename=BenningtonFax4.tif&customerid=68dd6ce8e9bb4fec8fedc43b49514d24&batchexternalid=&buyerid=68dd6ce8e9bb4fec8fedc43b49514d24&documenttype=SWEGE2&sortingmethod=OneDocumentPerFile HTTP/1.1
Content-Type: application/octet-stream
Accept: */*
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: d68c687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=E1F32D1F16BF04576E7B210722AF1B9920D5A0255874A80CCCDE5B8674F8701FA561B611A00998C90F8CB4B1A85682CDB1B553D7EA09A33F5B04AC54A28E64B43EA08163A5CD2B618222A04BC97E82D13F0C4835E0709388B8FF55775867C93F63B197F9E4AD7F11D64B419EEAD19623986AAC6B1528877A13B40CB76CBC089C7B001F391D7B05C59CCD0D118755DAB27737FFC5BC268E10DF9E34C8945DD76B23F490CCC7C4674C670A54BEE9EF736B49B9E30EE7F9FFECE173C8AA72BF94481DF6B5ECBA1B55A8676679842A70499B712D0F315819F42BA179D924E0E202DB; 
x-rs-host=somepartner.readsoftonline.com
Content-Length: 19838
Accept-Encoding: gzip, deflate
Connection: Close

binary image data...]

Click here to see the example with actual binary image data.

UploadMasterDataObjects

PUT https://services.readsoftonline.com/masterdata/rest/88dd6ce8e9bb4fec8fedc43b49514d24/masterdataobjects/Department HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Encoding: gzip,deflate
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=E5C93B76034307BB869F136174C1B3C85EAD045AFB135B2F84A032BCAA84DE65DC45DC57932BCB57CAA1C387C4215C5089911B77FE5FDFA4EEB34B87A6B142F85ABC27545877E9C983952E200C67704BCE1436CB91E3429AAC474896D452DDE6C316B70EABE48B777B4AE4A2431CE8D4F95FD56CAB42C737108E18C0D25DA50592CE8D9CAF94A81544D667FD04D3EE2302126794AEDD0F4B5D73933F80FCC9193DD3ED45D6155697CA24FAD219B12EFCDD1060C7AB839C0DE99183604AFCBED5DEB1C055327AB958EF8601FE86B747E2B8AB540610E8A2E7637C30F93FCB6E9F; 
x-rs-host=somepartner.readsoftonline.com
Content-Length: 201
Connection: Close

[{"Value":"DPA001","Name":"IT","Description":null,"Active":true},{"Value":"DPB002","Name":"Finance","Description":null,"Active":true},{"Value":"DPC003","Name":"Sales","Description":null,"Active":true}]

UploadSuppliers

PUT https://services.readsoftonline.com/masterdata/rest/88dd6ce8e9bb4fec8fedc43b49514d24/suppliers HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Encoding: gzip,deflate
x-rs-culture: en-US
x-rs-uiculture: en-US
x-rs-version: 2011-10-14
x-rs-key: dddc687e2d3e45bdb842df2e78123f3d
Host: services.readsoftonline.com
Cookie: x-rs-auth-v1=E5C93B76034307BB869F136174C1B3C85EAD045AFB135B2F84A032BCAA84DE65DC45DC57932BCB57CAA1C387C4215C5089911B77FE5FDFA4EEB34B87A6B142F85ABC27545877E9C983952E200C67704BCE1436CB91E3429AAC474896D452DDE6C316B70EABE48B777B4AE4A2431CE8D4F95FD56CAB42C737108E18C0D25DA50592CE8D9CAF94A81544D667FD04D3EE2302126794AEDD0F4B5D73933F80FCC9193DD3ED45D6155697CA24FAD219B12EFCDD1060C7AB839C0DE99183604AFCBED5DEB1C055327AB958EF8601FE86B747E2B8AB540610E8A2E7637C30F93FCB6E9F; 
x-rs-host=somepartner.readsoftonline.com
Content-Length: 1238
Connection: Close

[{"SupplierNumber":"1001","Name":"Anconia Corp","Description":null,"TaxRegistrationNumber":null,"OrganizationNunmber":null,"Street":null,"PostalCode":null,"City":null,"CountryName":null,"PaymentTerm":null,"PaymentMethod":null,"CurrencyCode":null,"Id":null,"Location":null,"State":null,"BankAccounts":[]},{"SupplierNumber":"1002","Name":"Veiraoou Groygguoo Company","Description":null,"TaxRegistrationNumber":null,"OrganizationNunmber":null,"Street":null,"PostalCode":null,"City":null,"CountryName":null,"PaymentTerm":null,"PaymentMethod":null,"CurrencyCode":null,"Id":null,"Location":null,"State":null,"BankAccounts":[]},{"SupplierNumber":"1003","Name":"Raxaf Negooo Limited","Description":null,"TaxRegistrationNumber":null,"OrganizationNunmber":null,"Street":null,"PostalCode":null,"City":null,"CountryName":null,"PaymentTerm":null,"PaymentMethod":null,"CurrencyCode":null,"Id":null,"Location":null,"State":null,"BankAccounts":[]},{"SupplierNumber":"1004","Name":"Polychemtex Inc","Description":null,"TaxRegistrationNumber":null,"OrganizationNunmber":null,"Street":null,"PostalCode":null,"City":null,"CountryName":null,"PaymentTerm":null,"PaymentMethod":null,"CurrencyCode":null,"Id":null,"Location":null,"State":null,"BankAccounts":[]}]