Introduction

Mastering the Transition: A Guide from SOAP to RESTful APIs

Welcome to our comprehensive guide on transitioning from SOAP to RESTful APIs. In this guide, we will walk you through the steps and best practices to smoothly migrate your legacy SOAP-based services to modern REST APIs, enabling you to embrace the advantages of a more flexible and efficient communication protocol. This introduction will show you 7 mains principles between your current SOAP format and the format that you are going to implement.

On this page

• Data Formats
• Identification and Headers
• Parameters Instead of Body Payload
• URL Parameters vs. Query Parameters
• Pagination Methods
• Capitalization, Field Naming & Data Format
• Response Codes and Error Handling
• To conclude

Data Formats

This section covers the differences in data formats between SOAP and REST APIs. Our SOAP API are using XML format, while our REST API supports the JSON formats. We’ll explore how to adapt your data format to meet the requirements of a RESTful API. JSON is more lightweight and human-readable, making it a preferred choice in RESTful APIs. This change allows for simpler data exchange and easier parsing.

<example>
	<name>Octopia</name>
	<streeNumber>12</streetNumber>
	<street>Main Street</street>
</example>

{
  "exemple": {
    "name": "Octopia",
    "streetNumber": 12,
    "street": "Main Street"
  }
}

Identification and Headers

In the RESTful world, authentication and identification of clients differ significantly from SOAP.

Instead of relying on an embedded token in the payload, our REST APIs employ OAuth 2.0 for secure client identification.

{
  "access_token": "eyJhbG.eyJleHAiOjE2O.K_d4gGRlh",
  "expires_in": 7200,
  "refresh_expires_in": 7200,
  "refresh_token": "eyJhbGciOiJ.eyJleHAiO.arJwm6CI_Uxnkg",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "f4c02b45-9110-a368-1ad080ee9471",
  "scope": "email profile"
}

In addition, headers play a crucial role in REST requests and responses, allowing you to convey metadata, such as content type or authorization, ensuring proper communication with the API. Because our API’s are REST there are based on HTTP protocol.

As example :

{
  "bookName": "This Good Story"
}

{
  "bookId": "B1001"
  "bookName": "This Good Story"
}

Here we have shared that the content sent is on JSON format (Content-Type), we attend to received JSON content in answer (Accept). We authenticated our self with the Bearer Token shared in Authorization.

Parameters Instead of Body Payload

One of the fundamental differences in REST is the usage of parameters rather than embedding data within the request body. In SOAP, data is sent in the payload, but in REST, parameters are commonly included in the URL or query string. This shift simplifies request handling and enhances the clarity of the API calls.

<GetOrderList>
    <orderFilter>
      <CreationDate>2023-12-25T10:00:00.00</CreationDate>
        <FetchOrderLines>true</FetchOrderLines>
        <States>
            <OrderStateEnum>AcceptedBySeller</OrderStateEnum>
        </States>
    </orderFilter>
</GetOrderList>

URL Parameters vs. Query Parameters

In the REST API design, understanding the distinction between parameters included in the URL path and those in the query string is essential. Parameters in the URL path are often used to identify a specific resource, while query parameters are used to filter or modify the results returned by the API. This distinction provides greater flexibility and clarity in your API.

As example:

Query Parameters

GET /orders?createdAtMin=2023-12-25T10:00:00&status=AcceptedBySeller

Here the parameters are listed at the end of the path (/orders) and start with a question mark (?) there are separated by a ampersand (&).

Path Parameters

GET /orders/1001/invoices

Here the parameter orderId is directly in the path (1001). It refers to a specific order ressource.

Path and Query Parameters

GET /orders/1001/invoices?createdAtMin=2023-11-07

Here the parameter orderId is directly in the path (1001). It refers to a specific order ressource. Also a filter has been added in order to retrieve only orders created at min on November 07th 2023.

Pagination Methods

When dealing with large datasets in RESTful APIs, there are two common approaches to pagination: cursor-based pagination and index-based pagination.

• Cursor-based Pagination: In this method, pagination is controlled using parameters like limit and cursor. The limit parameter determines the number of items to fetch per page, and the cursor parameter specifies the starting point for fetching data. This approach is suitable for scenarios where data order may change between requests and/or when there is a large number of data to return.
• Index-based Pagination: On the other hand, index-based pagination employs parameters such as pageSize and pageIndex. pageSize defines the number of items per page, while pageIndex indicates the specific page to retrieve. Index-based pagination is well-suited for situations where the data order remains relatively stable, making it easier to navigate through the dataset using page indices.

{
  "itemsPerPage": 4,
  "items": [
    {
      "orderId": "1001"
    },
    {
      "orderId": "1002"
    },
    {
      "orderId": "1003"
    },
    {
      "orderId": "1004"
    }
  ]
}

{
  "itemsPerPage": 4,
  "items": [
    {
      "orderId": "1001"
    },
    {
      "orderId": "1002"
    },
    {
      "orderId": "1003"
    },
    {
      "orderId": "1004"
    }
  ]
}

For more information about pagination please explore our API documentation.

Capitalization, Field Naming & Data Format

Capitalization & Field Naming

Proper capitalization and field naming conventions are essential in REST API design. Consistent naming ensures clarity and ease of use for consumers of your API. In REST, we are using camelCase for field names and for resources and finally snake-case for endpoints.

GET /orders/snake-case/example

Response

{
  "camelCase": "Example1",
  "camelExample": "Example2"
}

Data Format

In our REST APIs, we adhere to industry standards for data representation to ensure consistency and interoperability. Two commonly used standards are

• ISO 8601
• ISO 3166

ISO 8601 is a widely accepted format for representing dates and times. It provides a well-defined and unambiguous way to express date and time information, making it easier for different systems to understand and exchange time-related data. For example, it specifies a format like

• YYYY-MM-DDTHH:MM:SS

ISO 3166, on the other hand, is a standard for country and region codes. It defines two-letter and three-letter codes for countries and their subdivisions, facilitating the identification of geographical locations in a standardized manner. These codes are invaluable in international applications and APIs that involve location data. For example :

• FR

By adhering to standards like ISO 8601 and ISO 3166, we ensure that our APIs are not only well-documented but also easily accessible and usable by a wide range of clients and developers, promoting better integration and data exchange.”

Response Codes and Error Handling

The mapping of response codes and error handling in REST APIs differs from SOAP. REST relies on HTTP status codes to indicate the success or failure of a request, providing more standardized and meaningful feedback to clients. Additionally, error details are often conveyed in JSON format within the response body, making it easier to understand and process error information.

The common HTTP code that we are using are standard, as example:

• Success Codes : 200 : OK | 201 : Created | 202 : Accepted | 204 : No-Content
• Error Codes : 400 : Bad Request | 401 : Unauthorized | 403 : Forbidden | 404 : Not Found | 409 : Conflict

In order to share the most complete and understandable errors, we are following the standard format :

• problem+json

The format follow a JSON format with the fields :

• type : A link to RFC 7231 which describe the error encountered
• title : A title for the error, explaining the generic status
• status : Error code return by the API
• detail : Readable explanation to understand the error
• instance : The path where the error has been generated

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Not authorized to view account details",
  "status": 401,
  "detail": "Your token is missing.",
  "instance": "/orders"
}

To conclude

By following these guide, you will successfully transition from a SOAP-based API, which relies on POST requests to a single url with payload, to a more versatile and modern RESTful API architecture, which supports various HTTP methods, JSON data, and OAuth 2 authentication, and employs URL parameters, query parameters, and standardized error handling. This transition will make your API more flexible, efficient, and developer-friendly.