Our older data validation services are getting a refresh to help future-proof them as well as to enable JSON and XML responses. The underlying systems that support our web services are constantly being upgraded and updated but the core framework has remained the same. Our goal is to take the older style web services and add support for more modern programming paradigms. The solution – moving to the WCF framework.

What is WCF?

The Windows Communication Foundation (WCF) is a framework for building service-oriented applications. This framework provided a large step forward for .NET based web services.

What came before WCF?

Before WCF there was an era of web services that were tightly bound to the Simple Object Access Protocol (SOAP) and Extensible Markup Language (XML). These methodologies worked well within their scope, but as time went on the standards for web services changed. Programmers tended towards solutions that were based around the emerging Representational State Transfer (REST) architecture.

Making the switch to WCF

By creating applications that adhere to the WCF standards, the resulting web services are loosely coupled. This results in web services that are accessible by nearly every platform. The switch to WCF-based web service allows us the flexibility to keep up to date with the latest programming paradigms without modifying the existing structure our clients are currently using. We can add new points of entry and output formats without breaking existing clients’ implementations. This means that changes on our end don’t result in expenses (programming implementation, debugging, testing, deployment) on your end. By leveraging the WCF framework, we are able to continually improve our data validation services while providing our customers with uninterrupted, real-time APIs that continue to perform and meet their expectations. Our customers can decide, at their convenience, if and when they want to take advantage of the improvements.

What are the extra features that WCF offers?

Endpoints – An endpoint provides a place for a client to connect. The endpoint simplifies the integration process by specifying a contract that the client must adhere to. It generally consists of a URL at which a client can connect, as well as various binding properties that will state how the data will be transferred. An additional feature that this brings to the table is the support for both JSON and XML serialization.

Service Metadata – The WCF framework makes it easy to publish metadata about the web service. The metadata can be published in various industry standards such as WSDL, XML Schema, or WS-Policy. Many programming languages have tools built for them that allow the easy consumption of web service metadata. As an example, check out how easy a WSDL can make your implementation.

Extensibility – The WCF framework has multiple points of extensibility to allow for precise control over the applications. This could range from modifications to the service host, the bindings, the channel layer, security, the metadata system, and the encoders/serializers. This level of control will allow us to adapt to future programming standards.

How do our service updates to WCF affect clients?

Our number one priority is to ensure that existing clients don’t notice a thing. We aim to transition to the new framework while keeping the old endpoints unmodified. This will prevent our clients from needing to invest time and money into their existing implementations. However, the features within the WCF framework will benefit anyone looking to use the new endpoints. These updates will add support for JSON and XML responses, as well as support for RESTful web service calls.

One thing that will not change with these updates is our commitment to making your implementations as frictionless and convenient as possible. We will be continuously rolling out WCF for our services going forward, and if you would like to know anything more about it, contact our technical team anytime. We are always happy to help.

REST is a popular architectural style that has been the go-to design for web-based APIs for years. The style has defining constraints, but it is not a protocol and there is no official standard. REST is like the pirate’s code in the Pirates of the Caribbean movie franchise, in that REST “is more what you would call guidelines than actual rules.” As such, not everyone follows the guidelines exactly or interprets them the same way.

This can lead to some confusion and debate as to what is and is not considered RESTful. At the same time, one can look at this flexibility as an opportunity to pick and choose what will work best for their needs. In this article, we briefly discuss some web API design options and explore some of their strengths and shortcomings.

What REST Is – And Isn’t

For some, REST simply means using a service that is not SOAP. SOAP is another widely used protocol, but some stay away from it due to its complexity and the extra overhead that it requires. You would be hard pressed to find a REST-related article where SOAP is not mentioned. You will likely find comments about how great REST is because REST uses JSON and SOAP uses XML.

People often mistakenly think that REST is defined by the JSON language format, and when they say they want a RESTful service what they really mean is they want a service that supports JSON. REST is not as simple as that, and it is not confined to any one language format: it is an architectural style and not a specific protocol. Conversely, JSON is not exclusive to REST, as JSON is also available in Remote Procedural Call (RPC) APIs.

So, with that out of the way, the rest of this article will assume that the reader is familiar with the general style of REST. If you wish to learn about REST in more detail then feel free to read the dissertation it was based on – or if you’re not into heavy reading, check out the REST wiki.

Comparing Three Web API Options

Now, let’s look at three different approaches you can use for web APIs:

• REST – Representational State Transfer (REST) web APIs are “resource” oriented. RESTful APIs synergize well with CRUD applications and other forms of data resource management and manipulation.
• RPC – Remote Procedural Call (RPC) web APIs are “action” oriented. They enable the user to call a remote method to complete an action as though it were local. This is similar to importing and using the methods from a local library API.
• Hybrid – Hybrid designed web APIs incorporate both the RESTful style and RPC-based design methods. Some RESTful APIs will include RPC design to add action methods where strictly RESTful resource-oriented methods are not appropriate.

Since REST is resource oriented it is also useful for resource discovery. For example, if a Service Objects client was interested in all the cities or ZIP codes for a state then a RESTful API for discovering those resources and drilling into them for details would be ideal. This approach will also work well for suggestion and IntelliSense applications where several queries to find an address would be acceptable.

By comparison, users looking for address validation could find that having to make several queries would be cumbersome – especially if their data is incomplete or partially invalid. Most of our users do not always have complete data, and lean on us heavily to parse through and correct any garbage or mistakes to fill in the gaps and return an intuitive and standardized response.

RESTful Example: Address Validation

Let’s briefly explore what creating a RESTful address validation service would look like. We’ll start by coming up with a way for the user to submit an address for validation.

For this exercise, the theoretical service will be hosted on the following domain and path.

Domain: example.serviceobjects.com

Path Format: /AddressValidation/{State}/{City}/{ZIP}/{AddressLine1}/{AddressLine2}

The above format lends itself more to address discovery and would be better suited with a /FindAddress path name; however, this application’s primary job is validation and not discovery so let’s continue.

Let’s test the service using the Service Objects office address as an example.

Path Example: /AddressValidation/CA/Santa Barbara/93101/27 E. Cota St #500/

Unfortunately, the above example will fail to validate correctly due to the pound/hashtag (#) character. We know that the # symbol is a special URL character and that it is used as a fragment identifier. Commonly referred to as anchor in HTML. Its inclusion means that the URL path is prematurely terminated at the # symbol.

In this case, the API can respond in a few ways. It can return an HTTP Status code of 400 (Bad Request), but that isn’t too helpful to the user. It can also accept the request, but since the service is unable to see anything past the # symbol, the full address will not be validated. This is problematic, not only because the full address is not being validated, but what would be an acceptable response from the service? Validating the address as-is would be misleading to the user, and the service itself is unaware that parts of the address are missing. In the end, for this example, it would be best for the service to return the 400 status code for safety.

Now let’s try a different path format:

Path Format: /AddressValidation/{State}/{City}/{ZIP}/{AddressLine1}/{UnitNumber}/{AddressLine2}

Path Example: /AddressValidation/CA/Santa Barbara/93101/27 E. Cota St/500/

The above path format and example work, but it requires the user to parse out the apartment number from the address beforehand, and it is still susceptible to malformed requests due to special URL characters.

As we have just demonstrated, the path parameter approach has some shortcomings. More details and examples are available in a past tutorial. Fortunately, REST is not limited to one way of making requests; however, depending on one’s interpretation this is where this service and many others start to deviate from RESTful guidelines.

Foregoing the path parameter approach entirely, we could use query string parameters or POST requests.

Query String Example: /AddressValidation?AddressLine1=27 E. Cota St #500&AddressLine2=&City=Santa Barbara&State=CA&PostalCode=93101

In the above example, the query string parameters can be URL encoded, and there is no fear that the full address will not be passed in. There is also the option to use POST, but using POST instead of GET to read a resource is generally not done as it goes against REST guidelines. However, it is not uncommon to see many services use POST in ways outside of the REST guidelines.

For presentation sake, let’s continue with our example using POST and JSON.

JSON POST Request: 

A strictly RESTful response would be as simple as an HTTP 200 status code with a response like this:

If we provided an invalid address, for example by changing the suite number from 500 to 5,000 which does not exist, the RESTful response would then potentially return an HTTP status code of 404 with an output of:

The above output examples are too simplistic and not informative enough. The service could return a status description of “Address Not Found”, but the user is still left with very little information to work with. Our users rely on our services to not just validate their data but to also help inform them on how to proceed with using their data.

Following the RESTful style guidelines, the output could also contain an Address ID that can be used to reference the address and list details for it.

This RESTful style is not quite user friendly in that it requires the user to perform two queries: one to verify the address, and another to retrieve details for it. A big part of the problem stems from REST being “resource” oriented whereas Validation and Verification services are “action” oriented; therefore, lending themselves more towards the RPC-based design.

That’s not to say that the RESTful service cannot be made more user friendly. A hybrid approach can be taken, and the service could be expanded to be more informative by adding parameters to retrieve additional data so that only one request query is needed.

Output:

However, using an RPC-based design and forcing it to try and conform to the RESTful style doesn’t necessarily lead to a better user experience.

Why Flexibility Is Important

REST, RPC and hybrid designs each have their own merits and uses. It’s important to choose a design that works best for the given situation. That’s why Service Objects chooses a hybrid approach for our services that leans more toward the RPC-based design, since it suits the action-oriented usage. With validation services there are often many gray areas and edge cases to deal with that work best with custom action-based verb commands.

In a RESTful style, custom verb commands are to be avoided, and some would argue that any use of them would, strictly speaking, not be REST. However, many services do make use of both in a hybrid approach and even Google’s API Design Guide states that , “both RPC APIs and HTTP REST APIs are needed for various reasons, and ideally, an API platform should provide best support for all types of APIs.” So, whether you want to use HTTP GET, POST or SOAP with XML or JSON, the Service Objects DOTS Web Services have you covered.