JSON API: Specification for building APIs in JSON



From the JSON API website:

If you’ve ever argued with your team about the way your JSON responses should be formatted, JSON API can be your anti-bikeshedding tool.

By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on what matters: your application.

Clients built around JSON API are able to take advantage of its features around efficiently caching responses, sometimes eliminating network requests entirely.

MockServer: Java tool to mock any system you integrate with via HTTP or HTTPS

MockServer logo


From the Mockserver web page:

Why use MockServer?

MockServer allows you to mock any server or service that you connect to over HTTP or HTTPS, such as a REST or RPC service.

This is useful in the following scenarios:


  • easily recreate all types of responses for HTTP dependencies such as REST or RPC services to test applications easily and affectively
  • isolate the system-under-test to ensure tests run reliably and only fail when there is a genuine bug. It is important only the system-under-test is tested and not its dependencies to avoid tests failing due to irrelevant external changes such as network failure or a server being rebooted / redeployed.
  • easily setup mock responses independently for each test to ensure test data is encapsulated with each test. Avoid sharing data between tests that is difficult to manage and maintain and risks tests infecting each other
  • create test assertions that verify the requests the system-under-test has sent

De-coupling development

  • start working against a service API before the service is available. If an API or service is not yet fully developed MockServer can mock the API allowing any team who is using the service to start work without being delayed
  • isolate development teams during the initial development phases when the APIs / services may be extremely unstable and volatile. Using MockServer allows development work to continue even when an external service fails

isolate single service

  • during deployment and debugging it is helpful to run a single application or service or handle a sub-set of requests on on a local machine in debug mode. Using MockServer it is easy to selectively forward requests to a local process running in debug mode, all other request can be forwarded to the real services for example running in a QA or UAT environment

Swagger 2.0: Open source REST API framework

[Swagger 2.0 logo


From the Swagger 2.0 Github page:

The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.

Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. Swagger-enabled APIs expose JSON files that correctly adhere to the Swagger Specification, documented in this repository. These files can either be produced and served statically, or be generated dynamically from your application.

Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.

Swagger does not require you to rewrite your existing API. It does not require binding any software to a service–the service being described may not even be yours. It does, however, require the capabilities of the service be described in the structure of the Swagger Specification. Not all services can be described by Swagger–this specification is not intended to cover every possible use-case of a REST-ful API. Swagger does not define a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a REST API.