REST connector field descriptions
Learn about the key fields used to set up REST connectors, such as API URLs, methods, parameters, and authentication, to connect with external REST APIs.
- Connector
-
A component or module that allows interaction with an external API by handling authentication, making requests, and processing responses.
- REST (Representational State Transfer)
- An architectural style that is used for designing networked applications. It uses standard HTTP methods (such as GET, POST, PUT, DELETE) and is based on stateless communication between client and server. REST connectors enable interaction with any external REST APIs, whether they are internal systems, third-party services, or cloud applications.
- Client/server Architecture
- REST uses a client/server model where the client and server are separate entities. The client makes requests, and the server processes them and returns the appropriate responses.
- Statelessness
- Each request from a client to a server must contain all the information that is needed to understand and process the request. The server does not store any state between requests.
- Pre-built REST connectors
- A set of predefined connectors provided by the webMethods Integration platform for services like Salesforce, Google, and others.
- Custom REST connectors
- Create connectors by providing the necessary API details (such as URL, headers, and authentication methods) for any REST API you want to connect to.
- Uniform Interface
- RESTful services have a consistent, standardized way to interact with resources, typically by using URLs to represent entities and HTTP methods to do operations on them.
- Resource
- A data entity or object that is exposed by the API (for example, users, orders, products). Each resource has a unique URL, and clients interact with these resources using standard HTTP methods to run operations.
- REST Action
- Represents a specific operation or endpoint within a RESTful API, typically corresponding to Create, Read, Update, or Delete (CRUD) operations. A REST action is structured with several key components, including HTTP Methods, Headers, Request, Response, Parameters, and Error Handling. These components define how the action is performed and what data is involved.
- Method (HTTP Method)
-
The type of operation to do on a resource such as:
- GET - Retrieves data from the server.
- POST - Submits data to the server, often to create a new resource.
- PUT - Updates an existing resource or creates it if it does not exist.
- DELETE - Removes a resource from the server.
- PATCH - Partially updates a resource.
- API URL or Endpoint
- Full URL that you use to make the API request, which includes both the base URL and the resource path, for example, https://rest.example.com/users/123orders. It is the login endpoint URL to initiate communication with the SaaS provider. To get the endpoint, go through the SaaS provider documentation available on the internet.
- Base URL or API Server URL
- The root URL of the API that typically includes the domain and any base path, for example, https://rest.example.com/.
- Resource path
- Part of the URL that specifies the resource and how it is structured, for example, /users/{user_id}, /orders.
- Parameters
- Values that can be passed with a request to modify the behaviour or specify criteria for the request. These parameters help the server process the request and return the correct response. Parameters are of several types such as path parameters, query parameters, or header parameters.
- Path Parameters (URL parameters)
- Dynamic values within the URL path that are replaced with actual values to specify a particular resource. Path parameters are placed in the URL directly within curly braces {}. For example, /users/{user_id}, where {user_id} is the dynamic value that indicates the user’s ID.
- Query Parameters
- The key-value pairs added to the URL to filter, sort, or paginate data in a REST API request.
They appear after the ? symbol and are separated by & when multiple parameters are used. For
example, /products?category=electronics&sort=price.
For example, an API resource path with a base URL, endpoint path, path parameters, and query parameters is explained as follows.
Full Resource Path - https://rest.example.com/users/{user_id}/orders?status=shipped&sort=date&page=2&limit=10
Explanation
- Base URL - https://rest.API.com is the root URL of the API.
- Endpoint Path - /users/{user_id}/orders specifies that you are accessing the orders of a specific user. The {user_id} is a path parameter that is replaced with an actual user ID, for example, /users/123/orders.
- Path Parameter - {user_id} is replaced with the actual ID of the user whose orders you are querying, for example,/users/123/orders.
- Query Parameters - ?status=shipped&sort=date adds filtering and sorting options to the request. Here, status=shipped filters orders marked as shipped, sort=date sorts the results by order date, page=2 retrieves the second page of results, and limit=10 restricts the response to 10 users per page.
So, an actual request looks like: https://rest.example.com/users/123/orders?status=shipped&sort=date
- Form Parameters
Form parameters are used to submit form data, commonly with POST, PUT, or PATCH requests and are passed in the request body. They are key-value pairs and can be transmitted in formats like application/x-www-form-urlencoded (standard form) or multipart/form-data (for file uploads).
POST https://rest.example.com/v1/usersName=John+Doe&email=john.doe %40example.com&age=30
- Authentication
-
The process of verifying the identity of the user. Every Saas provider has their own authentication mechanism to provide authorized access to its APIs. You need to get the authentication details from the SaaS provider documentation. For example, for Twitter, go to https://apps.twitter.com and then get the credentials. For Twitter, the authentication is OAuth V1.0a, which you can get from https://apps.twitter.com.
- Headers
- Key-value pairs are included in the request or response to provide additional information or
control the behavior of the request or response. Header parameters are typically used for
authentication, content type specification, and caching. Common headers are,
- Authorization - Used to send credentials, for example, Bearer token.
- Content-Type - Specifies the type of data being sent, for example, application/JSON.
- Accept - Specifies the expected response format, for example, application/JSON.
- User-Agent - Identifies the client that initiates the request, such as a web browser or mobile app.
- Body
-
The content sent with requests, typically in JSON or XML format, that contains the data to be processed by the API. This is typically used with methods like POST, PUT, and PATCH where data needs to be sent to the server to create, update, or modify resources.
For example, a request body with parameters like name, email, and age that the server uses to create a new user is as,
POST https://rest.example.com/v1/users Content-Type: application/json { "name": "John Doe", "email": johndoe@example.com, "age": 30 } - Response
-
The data returned by the API after processing a request, typically in JSON or XML format. The response includes a status code that indicates the success or failure of the request, along with the results in the response body.
- Response Body
-
The body often contains the requested data or a message about the result, typically in JSON or XML format. For example, the response body that contains parameters like ID, name, and email of the user is as
GET https://rest.example.com/v1/users?(123) Content-Type: application/json { “userId”: “123”, “name”: “John Doe”, “email”: “johndoe@example.com” } - Status Code
-
A numeric code returned by the API to indicate the outcome of the request, for example,
- 1XX - Informational
- 2XX - Success
- 3XX - Redirection
- 4XX - Client error
- 5XX - Server error
- Rate Limiting
- A technique used to restrict the number of requests an API client can make within a specified time frame, helping to prevent abuse and promote fair usage.
- Timeout
- The maximum time the client waits for a response from the apiserver before an error is generated.
- Webhooks
- A method for APIs to send real-time notifications to external services when certain events occur, for example, sending an email when a new order is placed.
- API Key
- A unique identifier used to authenticate requests to an API, often included in request headers or as a query parameter.
- Proxy
-
A server that acts as an intermediary between a client and the target API, often used to improve performance or handle security and routing.
- Payload
- The data is sent in the body of a request (typically for POST and PUT requests) or response.
- Callback URL
- A URL provided by the client where the server will send responses or notifications after completing a process (common in OAuth flows).
- Swagger or OpenAPI
- A specification for describing RESTful APIs, often used to auto-generate API documentation and client libraries.
- JSON or XML Format
- REST APIs typically use lightweight data formats like JSON (JavaScript Object Notation) or XML (eXtensible Markup Language) for data exchange. JSON is more commonly used because of its simplicity and better compatibility with modern web technologies.
- API Specification type
- An API specification type is a standardized format or framework that is used to define and describe the structure, behaviour, and interactions of an API. It outlines how the API must be used, including details such as endpoints, request response formats, methods, and parameters. Common API specification types include OpenAPI, RAML, GraphQL SDL, WSDL, and AsyncAPI, each serving different API styles (such as REST, SOAP, or GraphQL) and use cases. These specifications help ensure consistent API design and provide clear documentation for developers.