Working with ERN APIs

At some point you'll need one or more MiniApps to interact with your mobile application--to access data or to trigger an action. Or, your mobile application may need to interact with your MiniApps. That's where ERN APIs come into play.

Powered by the ERN bridge and automatically generated by Electrode React Native from a Swagger schema, ERN APIs provide clearly defined methods of communication between the native Android or iOS side and the JavaScript side.

There are two components to ERN APIs: the API project itself and the API implementation.

The API project

ERN automatically generates the API project based on a Swagger schema. The generated API results in a cross platform API project that includes the client code of the API, for all three platforms (JS/Android/iOS), along with the optional API models. Any ERN MiniApp or mobile application can use this ERN API.

The generated API also contains the necessary hooks to implement the API. For example if your movie API contains a getAllMovies client request, the API also includes code to process the request and return the result --in this example, the collection of all movies.

The implementation of an API is not part of the API itself. The API project and the API implementation remain separate. One of the reason is to allow multiple implementations for any given API and offer the possibility to switch between implementations. Once the API is generated, you should not modify it in any way. The API contains only generated code. Any regeneration of it (for example, following a schema update) will actually overwrite any custom user code modifications.

Generated APIs have the following naming convention: react-native-[name]-api

API implementation

API implementations aren't completely generated for you--for obvious reasons, Electrode React Native can't know what your implementation will actually do. However, ERN still generates some of the code to help you kickstart ERN API implementations projects.

An API implementation executes a specific API method. For example, it implements the actual logic behind the getAllMovies request. An API implementation is on one side only. For example, an implementation can be a native implementation (iOS and/or Android) or a JavaScript implementation--but not both. At least not in the same API implementation.

There can be multiple implementations for a given API. For example, it is possible to have a JavaScript implementation and a native implementation of the same API. And for any API, only one implementation can run during runtime.

Versioning APIs

ERN APIs have a few advantages compared to React Native native modules. Because ERN APIs are generated, they don't need a specific container injection (linking) configuration. Also, Electrode React Native is not as strict with API native compatibility checks compared to native modules.

For native modules versions, the platform will not allow a version mismatch. If two different versions (including patch versions) of an identical native module are used by two different MiniApps, the ERN platform won't allow adding both MiniApps. Native module versions must be an exact match--including the patch version.

However, for APIs (and API implementations), Electrode React Native is less strict with version checks, as long as you adopt the guidelines listed below for versioning your APIs.

  • Patch version bump
    Used when your API contains changes to the internal implementation and not to the public implementation. For example, from 1.0.0 to 1.0.1. Because APIs are fully generated and should not to be modified manually, this should only occur when you regenerate an API following a platform version update that contains internal changes such as bug fixes or improvements to our API generator.

For API implementations, you should patch bump if you are making modifications to your implementation.

  • Minor version bump
    Used when your API contains new requests or new events. For example, from 1.0.0 to 1.1.0.

  • Major version bump
    Used when your API contains breaking changes to its public implementation. For example if you remove or rename an existing request or event. For example, from 1.0.0 to 2.0.0.

Electrode React Native offers more flexibility for deploying MiniApps that are using API versions that are not strictly aligned with API versions defined in the container.

  • API with a different patch version
    Used when trying to deploy a MiniApp that contains an API version that exists in the container with a different patch version--Electrode React Native assumes binary compatibility in any case.

  • API with a different minor version Used when trying to deploy a MiniApp that contains an API version that exists in the container with a different minor version--Electrode React Native assumes binary compatibility only if the version stored in the container is greater than the one used by the MiniApp.

  • API with a different major version Used when trying to deploy a MiniApp that contains an API version that exists in the container with a different major version--Electrode React Native considers binary incompability and does not allow deployment.

API guidelines

While the recommended approach to implement ERN APIs is in a dedicated standalone project, which favors reuse and allows for switching implementations, it might not be possible in your context to implement a standalone API. For example if your native API implementation is dependent on your mobile application itself, you might want to perform the API implementation directly inside your mobile application. This is possible, however we don't recommended this tight coupling approach.

If possible, MiniApps should not directly depend on API implementations; however, this makes switching between API implementations for the same API more complex. MiniApps should therefore ideally only depend on APIs. MiniApps can have some API implementations as development dependencies only. For example, if we consider an API with a native implementation of it (iOS and Android), it can be possible to have a cross-platform JavaScript mock implementation of it, that can be used during development to launch the MiniApp standalone.

Generated standalone API implementations have the following naming convention: react-native-[name]-api-impl

  • ern create-api
    Creates (generates) a new API project based on a Swagger schema

  • ern regen-api
    Regenerates an existing API project following Swagger schema updates

  • ern create-api-impl
    Creates (generates) a new API implementation project (native or JS)

results matching ""

    No results matching ""