Introduction

Development Cycle

This is section is about how to use ApiGear to create SDKs with the ObjectAPI.

tip

Feel free to jump directly to our demos over at github. They showcase two different APIs in several languages including applications which use the API modules.

Now, that you know the basics about the ObjectAPI and how to create SDKs using ApiGear, we provide some demos and hints for real world projects.

We will cover starting from scratch as well as updating an existing API, previously created using ApiGear. Our demos are implemented using the same process as described below.

Cycle Overview

The graphic describes the development cycle using ApiGear.

Like every modern development tool ApiGear fully supports an agile development approach. You can start with a minimal API definition and then iteratively add more functionality or change existing details. Theoretically, you could even rewrite the whole API. However, using the API first approach will help you design more stable and high quality APIs.

Define API

As with every API first approach you start at defining your ObjectAPI module. This can be done using the ApiGear Studio or the ApiGear CLI. An API module is a simple document following the ObjectAP specification.

Create SDK

Once you have created one or several API modules you are set to create your first SDK. Therefore you choose one of our expert engineered SDK templates and a SDK runner for your project.

The SDK runner will create a .zip file for you to download.

Apply Changes

The aforementioned SDK .zip file consists of several different files depending on the SDK runner setup and chosen programming language.

Assuming you chose the "full package including scaffolding" then you have the following types of files:

1. The plain API in your preferred language
2. A stub implementation derived from this API with a basic implementation
3. A suite of test files covering the stub implementation
4. Project files to instantaneously build the whole API module and execute the test cases
5. Additional adapters created by ApiGear to provide API analytics insights.

From here on we recommend a split strategy depending on whether you created the API module for the first time or whether you want to update an existing implementation.

First run

The easiest way to set your project up for long time API updates is to create an ini(tial) folder within your project and extract the SDK unmodified in this folder. Afterwards you just simply copy this ini folder to a sol(ution) folder. You should then commit this state as initial version to be able to always rollback.

Once this is done you can start replacing the API stub implementation in the sol folder with your business logic and the same time update the test stubs to cover the real API behavior.

Updating existing APIs

When you have set up your project as described in the first run using a ini and sol folder - or a similar setup - you can now easily apply updates to your API using the following steps.

• extract the updated SDK unmodified into the ini folder. A diff of your preferred source control tool should only should the auto generated changes based on your API modification
• use a compare and merge tool to go over the differences of the updated ini folder and your existing implementation in the sol folder
• only apply the interface changes without overwriting your business logic

This process might sound cumbersome on first sight but is really easy and straight forward to use.

Create application

Now, that we have our API module in place we can start using it an application. Depending on whether it is the same team or a different team implementing the application, they can use the module either with a stub implementation, a simulation adapter or the real business logic. There is no dependency anymore - the API module and the application can be both developed in parallel based on the commonly defined API description.

Our demos were developed the same way as described above. Small increments at a time, super fast and with high quality built in. The applications are stored in the app(lication) folder.

Gain insights

With the upcoming feature ApiGear analytics you will gain full insight into your customers API usage. Based on this highly valuable feedback you are able to make fully informed decisions on which feature to extend or which could be spared for future efficiency and customer satisfaction.