API - Web Service
Yoswit REST API provides a powerful, convenient, and simple Web services API for interacting with Yoswit. Its advantages include ease of integration and development, and it’s an excellent choice of technology for use with mobile applications and Web 2.0 projects. Yoswit REST API uses the same underlying data model and standard objects as those in SOAP API. See the SOAP API Developer's Guide for details. Yoswit REST API also follows the same limits as SOAP API.
To use the API requires basic familiarity with software development, web services, and the Yoswit user interface.
Use this introduction to understand:
- The key characteristics and architecture of REST API. This will help you understand how your applications can best use the Yoswit REST resources.
- How to set up your development environment so you can begin working with REST API immediately.
- How to use REST API by following a quick start that leads you step by step through a typical use case
Completing the prerequisites makes it easier to build and use the quick-start sample.
- Install your development platform according to its product documentation.
- Become familiar with cURL, the tool used to execute REST requests in this quick start. If you use another tool, you should be familiar enough with it to translate the example code.
- Become familiar with JSON which is used in this quick start, or be able to translate samples from JSON to the standard you use.
- Enable an SSL endpoint in your application server.
- Become familiar with OAuth 2.0, which requires some setup. We provide the steps, but it will help if you are familiar with the basic concepts and workflow.
- Read through all the steps before beginning this quick start. You may also wish to review the rest of this document to familiarize yourself with terms and concepts.
Step One: Obtain a Yoswit Developer Edition Organization
Set up a Developer Edition organization for testing your code.
If you are not already a member of the mob-mob.com developer community, go to mob-mob.com and follow the instructions for signing up for a Developer Edition organization. Even if you already have Enterprise Edition, Unlimited Edition, or Performance Edition, use Developer Edition for developing, staging, and testing your solutions against sample data to protect your organization’s live data. This is especially true for applications that insert, update, or delete data (as opposed to simply reading data).
If you already have a Developer Edition organization, verify that you have the API Enabled permission. This permission is enabled by default, but may have been changed by an administrator. For more information, see the help in the Yoswit user interface.
Step Two: Set Up Authorization
Setting up OAuth 2.0 requires that you take some steps within Yoswit and in other locations. If any of the steps are unfamiliar, see Understanding Authentication or the Yoswit online help. The following example uses the Web server OAuth flow.
- Create a new connected app if you haven’t already done so.
- In Yoswit Classic, from Setup, enter Apps in the Quick Find box, select Apps (under Build | Create), then click the name of the connected app.
- In Lightning Experience, from Setup, enter Apps in the Quick Find box, select App Manager, click , and then select Edit.
Click Enable OAuth Settings and specify your callback URL and OAuth scopes. The Callback URL you supply here is the same as your Web application’s callback URL. Usually it is a servlet if you work with Java. It must be secure: http:// does not work, only https://. For development environments, the callback URL is similar to https://localhost:8443/RestTest/oauth/_callback. When you click Save, the Consumer Key is created and displayed, and a Consumer Secret is created (click the link to reveal it).
From your Java or other client application, make a request to the appropriate Yoswit token request endpoint that passes in grant_type, client_id, client_secret, and redirect_uri. The redirect_uri is the URI that Yoswit sends a callback to.
Store the access token value as a cookie to use in all subsequent requests.
Once authenticated, every request must pass in the access_token value in the header. It cannot be passed as a request parameter.
Step Three: Send HTTP Requests with cURL
To interact with the Yoswit REST API, you need to set up your client application (we use cURL) to construct HTTP requests.
Setting Up Your Client Application
The Yoswit REST API uses HTTP GET and HTTP POST methods to send and receive JSON and XML content, so it is very simple to build client applications using the tool or the language of your choice. We use a command-line tool called cURL to simplify sending and receiving HTTP requests and responses.
cURL is pre-installed on many Linux and Mac systems. Windows users can download a version at curl.haxx.se/. When using HTTPS on Windows, ensure that your system meets the cURL requirements for SSL.
Sending HTTP Requests Using REST API Resources
Your HTTP requests to a REST API resource should contain the following information:
- An HTTP method (HEAD, GET, POST, PATCH, or DELETE).
- An OAuth 2.0 access token used to authenticate the request. For information on how to retrieve the token, see Quick Start.
- An HTTP ACCEPT header used to indicate the resource format (XML or JSON), or a .json or .xml extension to the URI. The default is JSON.
- The Yoswit REST resource.
- Any JSON or XML files containing information needed for requests, such as updating a record with new information.
The HTTP methods are used to indicate the desired action, such as retrieving information, as well as creating, updating, and deleting records.
- HEAD is used to retrieve resource metadata.
- GET is used to retrieve information, such as basic resource summary information.
- POST is used to create a new object.
- PATCH is used to update a record.
- DELETE is used to delete a record.
To access a resource, submit an HTTP request containing a header, method, and resource name.