In today’s software driven world life literately runs on code, from our smart phone alarm in the morning, coffee machine set to brew at 6am, to the drive to work where your Korean car intelligently reminds you its due for a service. Software is all around us and its here to stay.
While the above examples don’t need to communicate to the outside world, the manufacturers certainly did and there are many instances where cross platform communication is needed. It is possible for your smart phone to talk to your coffee machine or in-fact your car.
This compatibility can be achieved is numerous ways with the most common being an Application Programming Interface (API). Today every provider and his dog has an API exposing their services to be consumed by vendors and customers.
In computer programming, an application programming interface is a set of subroutine definitions, protocols, and tools for building application software. - Wikipedia
In software development it is common to develop microservices that run independently of other services. Instead of exposing functionality in code though a well defined class constructor the functionality is shared with an API.
I’m fond of RESTful services that accept and respond to JSON requests as this means a scripting language like PHP can consume and use a .NET Web API service. As long as the JSON request is documented and the authentication challenge is passed they can talk nicely.
The problem with the above scenario is software is not always segregated into LIVE, UAT, QA or stand box environments. A vendor could either only have a LIVE environment or in some cases the API is still being built. In this case the developer building the software to consume the API will only need to know a few things:
- The method signature to call, with Web API this can be as simple as
- The class structure to be represented as JSON notation:
This is simply a list of orders:
clientId 1 is placing an order for productId 91 (1 of) and productId 103 (2 of)
I created the above JSON online with codebeautify.org
This service is awesome as it allowed me to generate a sample JSON request, update it based on my order parameters and verify the JSON is valid.
- The expected response:
This can be the same list above with the id parameter now populated or simply a order list of id’s.
As long as the expected response is known (JSON in the body) and the response code is standard (200 ok, 404 not found, 500 error ect) the developer is good to go.
If the API is not ready for testing or is not available due to other constraints the developer can create a mock API using software such as SoapUI. This is a great tool that can be used to test existing APIs or to simply Mock the API response on the developers local machine. There is a tutorial online at www.soapui.org
The steps using my ‘save order’ example are:
- Create a new dummy REST request to ‘domain.com/api/saveorder’
- If you run this request you will get 404 as ‘api/saveorder’ doesn’t exist but I see some clown is squatting on ‘domain.com’
If it was a valid API the response would be shown. If you know the ‘LIVE to be’ details of your API you should rather use them as you can then use this test profile later.
- Now to mock the service to response with the JSON example simply right click and select ‘Generate REST Mock Service’ and give it a useful name such as
- The mock service will start right away on an available port - my test used 8089
- You can then stop the service and update several of the response property’s such as the HTTP status code, add header values and the body content type and values.
- You can now consume this service at http://localhost/api/saveorder using SoapUI
- You can also consume this from code, for simplicity all my applications are grouped under the solution ‘WebApiDemo’
a. Simply run ‘WebAPI’ from the IDE, note the port ~ example http://localhost:53610/
b. Stop the application and update ConsoleApplication.Program API value with the port (remember to re-build)
c. Run ‘WebAPI’ again from the IDE
d. Run manually run ‘\WebApiDemo\ConsoleApplication\bin\Debug\ConsoleApplication.exe‘
The above solution is made up of the following projects and the source code is available from GitHub
This is simply to demonstrate how to call the API from code. Changing the value of ‘var api’ switches between SoapUI and the WebAPI project.
Still on the fence with shared data models! The data model is ‘OrderModel’ which has some dummy propertys Id, ProductId, ClientId and OrderCount.
This is a .NET Web API project that has a ‘SaveOrderController’ which maps to ‘/api/saveorder/‘
The demo simply takes the posted ‘List
It has the ‘ApiKeyValidationAttribute’ which validates against apiPassKey which was passed in the header of the request.
If the validation/challange failes the API will respond with HttpStatusCode.BadRequest
Simple unit test project to test the public ‘Post’ method on the WebAPI controller
Another API development environment tool that works really well and has mocking abilities is POSTMAN - www.getpostman.com/postman