What are the similarities between SOAP and REST?

Many different programming languages, architectures, and platforms can be used to create applications. Sharing data between these different technologies is difficult because they have different data formats. Both SOAP and REST came into existence in an attempt to solve this problem.

SOAP and REST can be used to create APIs or communication points between different applications. The terms web service and API are used interchangeably. However, APIs are a broader category. Web services are a specific type of API.

The following are other similarities between SOAP and REST.

• Both protocols describe rules and standards for how applications create, process, and respond to requests for data from other applications;
• They both use the standardized Internet protocol HTTP to exchange information;
• They both support SSL/TLS for secure encrypted communication;
• You can use SOAP or REST to create secure, scalable, and fault-tolerant distributed systems.

When should I use SOAP and REST?

Before choosing between SOAP and REST, study the scenarios and requirements of API users. The following criteria are worthy of consideration.

Overall application design

Modern applications such as mobile and hybrid applications work better with REST APIs. REST provides scalability and flexibility to develop applications using modern architectural patterns such as microservices and containers. However, if you need to integrate or extend legacy systems that already have SOAP APIs built in, you may be better off continuing to use SOAP.

Security

Public APIs have lower security requirements and require more flexibility so that anyone can interact with them. Therefore, REST is the best choice when creating public APIs. Conversely, some private APIs for internal corporate tasks (e.g., reporting for compliance) may benefit from the tightened security measures in WS-Security of SOAP.

ACID Compliance

Do your API users require strict consistency and data integrity across the transaction chain? For example, financial transactions require the failure of an entire batch of data updates if even a single update fails.

SOAP has a built-in set of ACID properties. And SOAP may be better suited to meet high data integrity requirements. In this case, the REST API may need additional program modules to control state at the server or database level.

The post What is the difference between SOAP and REST? appeared first on Foaas.

Step 1: Choose a version control strategy

It is important to select an API version control strategy during the API design phase of the API lifecycle . This version management strategy should be common to all APIs in your portfolio. The earlier you think about versioning, the more likely you are to choose sustainable design patterns that will reduce the occurrence of critical changes. An early decision about API versioning will also help your team build a realistic roadmap for how your APIs will evolve to meet consumer needs for years to come.

Step 2: Confirm if a new version is needed

Change is an inevitable part of API development, but not every change requires a new version. Before deciding to release a new version, teams should evaluate the scope and impact of the change they want to make and determine if there is a way to do it in a backward-compatible way. For example, you might decide to add a new operation instead of changing an existing one. If there’s no way to avoid critical changes, you might consider holding off on introducing them until you release an exciting new feature that improves your customers’ experience.

Step 3: Update your documentation

If you’ve decided it’s time for a release of your API, it’s important to update your API documentation to include release notes. For example, you’ll need to communicate the reasons for the change, how it will affect consumers, and how you can access the new version. You may also want to include a release schedule and migration instructions, especially if you plan to eventually stop supporting the old version.

Step 4: Roll out the new version gradually

If possible, teams should release the new version of the API in stages, starting with a small group of users. They should then gather feedback from these users and address any issues before releasing the new version more widely. This approach helps teams ensure that the new version works as expected and provides valuable insight into how real consumers interact with the API.

Step 5: Cancel support for the old version

Once the new version is stable, teams should track adoption to assess how many users have successfully migrated to it. If adoption rates are as expected, teams can create and announce a timeline for discontinuing support for the old version. At this point, it is important to offer support to users who continue to use the old version, as they may need help migrating to the new version.

The post How to version the API? appeared first on Foaas.

What topics to include in Best practices

While many of the topics in API documentation are standard, there is usually a detailed list of things you need to know about working with APIs. This information is only available upon request from developers.

The list of topics may include topics such as:

• pagination,
• time ranges,
• fault tolerance,
• cache values,
• connectivity,
• timeouts,
• downtime,
• SSL,
• versions,
• testing and validation,
• exports,
• languages,
• number processing,
• resource expansion,
• notifications,
• CORS,
• localization
• and more.

Mailchimp

Mailchimp API best practices include tips on fault tolerance, using specific requests, authentication, cache values, connectivity, and registration. With fault tolerance, Mailchimp reminds developers that downtime sometimes happens, so they should plan to handle scripting accordingly if the API fails to respond. With ad-hoc queries, Mailchimp alerts users to the time it may take if a query is too generic and therefore returns too much information.

Coinbase

Coinbase does not link to topics such as best practices; instead, the navigation bar shows a list of topics. Pagination is one of these topics worth focusing on. How does pagination relate to the API? Suppose an API endpoint returns all the items in a user’s account. There could be thousands of items, and if all items were returned in a single response, it could take a long time for the API to collect and return a lot of data. As a result, like a Google search, the response returns a limited set, such as the first ten items, and then contains a URL that can be used to navigate to the next set of responses. Pagination refers to navigating to the next page of responses.

Earlier, defining the characteristics of REST, HATEOS or “Hypermedia as an application state engine” was mentioned. Links in responses that return more results are one example of HATEOS.

Programmatically processing a URL to get more responses can be quite a challenge. If you want all items returned and then filtered and sorted by finding specific values to retrieve, how would you do this using the URL returned in the response? The team can advise developers working with these scripts. Most likely, the endpoint will offer filters as parameters to apply to the endpoint so that the initial response contains the desired set of elements. This type of advice may be appropriate in API best practices.

The post Best practices API appeared first on Foaas.

For example, Python, C++, or Node applications implement API requests in different ways. Each language has its own way of constructing API requests. You can use Postman or Paw to automatically generate a simple request in a particular language. SDKs take implementation to another level. SDKs can include many more files or libraries as part of the implementation.

What is the technical writer’s role in documenting SDKs and sample applications

In the SwaggerHub guide, we learned how to automatically generate client SDKs in the SwaggerHub interface. Typically, if your development team proposes a client SDK, instead of an automatically generated SDK, there will be code that the development team prepares and tests. The development team often provides the SDK in multiple target languages depending on their user’s primary language, making it easier for users to implement the API.

For a technical writer of APIs, documenting SDKs and sample applications is a more difficult task, because SDKs require knowledge of one or more programming languages. The question of how much code a technical writer needs to know will be discussed in the Technical Writer Job module, so we won’t go into detail here. Usually developers don’t expect you to have a deep knowledge of several programming languages, but some understanding will be required to describe them and review documentation. When deciding whether to call a block of code a function, class, method, or other name, you need to have a basic understanding of the terms used in the language.

If the language is unfamiliar, you can just take what engineers write, clean it up a bit, try going through the steps to get any sample applications working, and see what feedback comes from users. Usually, if you can install and work with a sample app and make sure that the basic documentation for running the app works and what the app does, that might be enough. But of course, making any significant contribution to the SDK documentation will require knowledge of the programming language in which the SDK is written.

The post SDK and sample applications appeared first on Foaas.

Where to list HTTP response and error codes

It is more practical for APIs to have one page with responses and error codes to the entire API. A separate page listing the status codes (instead of adding a status code to each endpoint) allows for more detail on each code without overcrowding other parts of the documentation. This approach reduces redundancy and the feeling of information overload.

On the other hand, if some state and error codes are more appropriate for certain endpoints than others, it makes sense to display such state and error codes on the endpoint description pages.

Such a strategy might be to call attention to any particularly important status or error codes for a particular endpoint, and then go to the centralized Response and Status Codes page for complete information.

Where to get error codes and statuses

Status and error codes may not be obvious in the API documentation. You will probably have to ask developers to provide a list of all status and error codes that are unique to the API. Sometimes developers hardcode the status and error codes directly into program code, and they don’t have easy ways to pass the full list (which also makes localization difficult).

As a result, it may require a tambourine dance to find all the codes. In particular, you may have to break the API to see all possible error codes. For example, if you exceed the rate limit for a particular request, the API may return a special error or status code. Such custom code should definitely be documented. In the API troubleshooting section, you can specifically post examples of how to retrieve error codes.

Status and error codes are helpful in troubleshooting problems

Status and error codes are particularly useful in troubleshooting. Thus, you can consider error codes as a supplement to the troubleshooting section.

Each part of the documentation can be useful in the troubleshooting section. The troubleshooting section can describe what happens when users go off the beaten path and stumble into the dark forest. Status codes are like clues to help users get back on the right path.

In the troubleshooting section, you can list error messages related to the following situations:

• using invalid API keys;
• use of invalid API keys;
• parameters do not match data types;
• API throws an exception;
• no data to return the resource;
• rate limit exceeded;
• parameters are outside the acceptable maximum and minimum limits;
• a mandatory parameter is missing from an endpoint.
• the error text must be accurately documented so that it appears easily in a search.

The post Error codes and statuses appeared first on Foaas.

In addition, without authentication, there would be no easy way to associate requests with specific user data. And there would be no way to protect against requests from malicious users who might delete another user’s data (for example, by removing DELETE requests for another user’s account).

Finally, there would be no way to track who is using the API or which endpoints are used most often. Clearly, API developers need to think about ways to authenticate and authorize requests to their APIs.

In general, API authentication and authorization serve the following purposes:

• authenticating requests to an API for registered users only;
• tracking who is making requests;
• tracking API usage;
• blocking or slowing down a user who exceeds speed limits;
• applying different levels of authorization for different users.

Different types of authorization

There are several methods of authorization. Below we’ll look at a few authorization options that are most common:

• API key;
• Basic Auth;
• HMAC;
• OAuth 2.0.

API key
Most APIs require authorization with an API key in order to use the API. An API key is a long string that is usually included either in the request URL or in the request header. The API key basically serves as a way to identify the person making the API request (authenticating to use the API). The API key can also be associated with the specific application that is registering.

APIs can give either a public or private key. The public key is usually included in the request, while the private key is treated more like a password and is only used when communicating between servers. On some API documentation sites, the API key is automatically populated in the sample code and API Explorer when you go to the site.

Basic Auth
Another type of authorization is called Basic Auth. With this method, the sender places a username:password pair in the request header. The username and password are encoded using Base64, which is an encoding method that converts the username and password into a set of 64 characters to ensure secure transmission.

HMAC (Hash-based message authorization code)
HMAC stands for Hash-based message authorization code and is a stronger type of authentication, more common in financial APIs. In HMAC, only the sender, and the receiver know the secret key, which is unknown to anyone else. The sender creates a message based on some system properties (e.g., the timestamp of the request plus the account ID).

The message is then encoded with the secret key and passed through a secure hashing algorithm (SHA – secure hashing algorithm). (A hash is an encrypted string based on the algorithm.) The resulting value, called a signature, is placed in the request header.

The API server (the recipient), upon receiving the request, takes the same system properties (request timestamp plus account ID) and uses the secret key (which is known only to the requestor and the API server) and SHA to generate the same string. If the string matches the signature in the request header, the request is accepted. If the strings do not match, the request is rejected.

OAuth 2.0.
One popular method of authenticating and authorizing users is OAuth 2.0. This approach relies on an authentication server to communicate with an API server to grant access. You can recognize that the OAuth 2.0 method is being used when you are prompted to log in using third-party services like Twitter, Google, or Facebook.

The post Consequences of API security shortfalls appeared first on Foaas.