Blog
Token
About Us
AiDOOS Wiki
Project Cost Estimation

Welcome to Knowledge Base!

KB at your finger tips

This is one stop global knowledge base where you can learn about all the products, solutions and support features.

Categories
All
CRM
Salesforce
ERP
SAP
Storage and Backups
Purestorage Netapp Nutanix
Cloud
AWS
Computing
IBM
Database
MongoDB MySQL PostgreSQL
DevOps
Docker Kubernetes Jenkins GitLab
Mobile
React Native Android
Web
React Angular PHP
Programming
Python
Products
CNC Software (Mastercam) 3D perception 7shifts

CRM-Salesforce

Salesforce Developers

Introduction

Welcome to the documentation for the Salesforce Optimization API. What is the Salesforce Optimization API? Our API (a grouping of functionalities) that is composed of endpoints which perform a single, specific task like repairing a vehicle route or scheduling a resource to perform service.

We have opened access to the API so you too can create amazing applications and products using our services. Unlike our suite of Salesforce products, the API is Salesforce agnostic and thus has utility in a wide variety of applications, for example:

  • OEM — create or improve functionality for an existing application.
  • SOLUTION IMPLEMENTATION — partners or firms that are building custom applications for a customer.
  • INDEPENDENT SOFTWARE VENDORS — build and sell your software.
  • INDIVIDUAL DEVELOPERS — people or teams are building proofs of concept or testing new ideas.

The API usage pattern is based on industry best practices and is the same experience to which you've become accustomed. As an example, consider routing optimization:

  1. Your code crafts a routing problem out of your data.
  2. Your code submits a routing problem request to the routing endpoint of our Optimization API.
  3. Our systems solve the routing problem and respond (typically within seconds) with a routing solution.
  4. Your code parses the response and does something amazing with it!

Salesforce Developers

Authentication

Accessing endpoints on the Salesforce Optimization API requires a valid API key associated with your account, and all clients must obtain authentication credentials before having access to Salesforce API's. Your API key is provided via the request header using the x-api-key parameter. Throughout the documentation, we assume this header is provided. Below is an example of a typical header JSON object:

API keys are used to track requests associated with an account for quota, billing, and analytics purposes. Please review the Terms of Service agreed to during sign-up, or contact support, if you have additional questions.

Code snippets like those below are provided for all endpoints and methods. If you find any are missing, not working, or incomplete, please submit a support request, and we'll update the docs immediately.

To provide context, consider the below examples where you would need to replace REPLACE_KEY_VALUE with your actual API key. A simple request in a shell might look something like this:

Alternatively, if you're more comfortable reading JavaScript:

Here is a final example in Python:

When you receive credentials, please take steps to secure them properly. Exposing credentials can result in unauthorized access, which can lead to billable events. To help keep your credentials secure, follow these best practices:

  • Do not embed credentials in code
  • Store credentials separately from the code base, for example using Docker Secrets or git-crypt
  • Set up account restrictions
  • Delete unused credentials
  • Regenerate credentials periodically
  • Automate detection of exposed keys using native functionality in platforms like GitHub or Gitlab, or add the functionality with tools like git-secret or git-secrets

The API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them wholly public and accessible to everyone, including any code on any site.

Read article

Salesforce Developers

Behavior

Methods

Any tool or programming language that has HTTP communication abilities, for example cURL or Postman or Python requests , can interact with our API by merely requesting the correct endpoint, for example /routing . All requests need to be made using the HTTPS protocol to ensure encryption and an extra layer of security. Additionally, most of our endpoints expect requests to be made in the standard JSON format. Our API's support the standard HTTP methods, e.g., GET , POST , and so on.

Encoding

All API's require the contents of request objects be encoded using UTF-8. To represent special characters in strings, use the %FF hexadecimal representation. For example, in German, the word "airports" is "Flughäfen" and converts to "Flugh%C3%A4fen." If you are unsure of the conversion, there are numerous online encoder/decoder tools and automated encoding/decoding in language specific libraries.

For example (in Python 3.0+):

For a full-fledged URI request (in Python 3.0+):

Success

All success responses include standard HTTP statuses consistent with IETF standards. The API returns a JSON object when a request is successful. The JSON object contents are specific to the resource and described in the detailed documentation for each resource. The API backend handles requests in one of two ways:

  • Synchronously : For smaller jobs (in terms of the number of unique locations), the request processes "quickly" (shorter than a connection timeout) and the response JSON body includes a result.
  • Asynchronously : For larger jobs, the request does not process quickly, and the response JSON body includes a jobid needed to poll the endpoint and retrieve a url to download the solution. Solutions are available at this URL for 24 hours from the timestamp included in the response header.

Failure

All failure responses include standard HTTP statuses consistent with IETF standards. In the event an error occurs, the response is a JSON with a top-level error code, error message, and other identifying information. All API errors return a JSON response with a human-readable comment describing the issue. Depending on the error returned, there may be additional objects to describe the error further. Note that if a client does not receive a response for a request within 29 seconds, the API returns an HTTP status code of 504 indicating a Gateway Timeout Error.

Read article

Salesforce Developers

Units of Measure

For units of measure, the Salesforce Optimization API uses the metric system. When in doubt, assume a standard metric unit. If you encounter uncertainty, please submit a support request, and we update the offending API to provide clarity.

  • Time: seconds
  • Distance: meters
  • Volume: arbitrary, but must be consistent across the entire request
  • Weight: arbitrary, but must be consistent across the entire request

The Salesforce Optimization API expects geographic coordinates in units of decimal degrees using the WGS84 coordinate system. The polyline format is used to encode a sequence of locations in a single string. Polylines appear in some endpoint responses, for example, the routes object in the response from the routing endpoint.

Time is expressed in two ways:

  1. ISO 8601: this is the most self-consistent, time zone independent form of time measurement and is useful for quickly parsing and processing times across many time zones. The ISO 8601 format enables users to take advantage of modern programming libraries and modules which are time zone aware.
  2. Unix time: Unix time represents a point in time as the number of seconds that have elapsed since 00:00:00 UTC on Thursday, 1 January 1970, minus leap seconds. Parameters expressed in Unix time are signed 64-bit integers. Why may you ask? So that the times are valid until 15:30:08 UTC on Sunday, 4 December 292,277,026,596... giving you plenty of time to worry about code refactoring and technical debt.

Time zone names and offsets are specified using the Internet Assigned Numbers Authority. This adoption ensures users can leverage modern DateTime parsing libraries such as CCTZ in C++ or datetime in Python or Date in Javascript.

Note that if a user submits a time as a string expression which includes a time zone offset, the time zone offset is converting to Unix time. If no time zone is given, then the API attempts to associate that particular time with a location and then the time zone of that location is used when converting to Unix time. The API maintains a private timezone service to facilitate this functionality.

To highlight the reasoning for the time format choices, consider a timestamp in seconds. Using the handy Python pytz module, one can process time in a generalized, robust manner using only a few lines of code:

Read article

Salesforce Developers

Versioning

Minor updates and bug fixes are implemented continuously and preserve existing API behavior. Significant updates that alter API behavior are released to a new URL leveraging versioning, for example https://sfoptapi.com/{apiVersion}/routing where {apiVersion} might be v1 , v2 , v3 and so on. The CHANGELOG tracks all changes made to the APIs. Changes that are considered backward compatible:

  • Changing a parameter from required to optional
  • Adding enumeration values
  • Adding new functionality

API versions are embedded in the URL to ensure that releases do not create a breaking change. For example, in the release from v1 to v2 , clients on v1 are not affected because the URL to v1 is still valid and consistent with the v1 specifications.

When a legacy API version reaches its end-of-life and will no longer be accessible, all users are notified 90 days in-advance to ensure that applications update to a newer API version. Also, requests to retired API versions receive a default error response with a 30x status code and message pointing to the latest version of that API.

Our documentation is built using the OpenAPI Specification, and the full spec for each API is available at the top of the API's docs page via the "Download" button. We encourage others to continue support of the OpenAPI Initiative to ensure harmonization among the universe of API's.

Read article

Salesforce Developers

Postman Collections

Run any of the examples provided in this section using our maintained Postman Collections. A "Public PROD Environment" ships with the Postman Collection. You need to edit this environment and replace the {{apiKey}} variable with your API key. If you do not have one yet, contact us to get one.

Read article