Custom Modules

Adding Modules

The information on this page will take you through adding various types of modules to Monarch. Deploying the modules is accomplished by simply packaging all of your custom code into a JAR file (or multiple JARs if you like) and copying it into the Monarch lib directory. Be sure to remove any old JAR versions if you are including the version number in the filename. The standalone start scripts will dynamically find your libraries and add them to the classpath. If you are running Monarch inside of an application server, then you will need to re-run bin/make-war or bin/make-war.bat to regenerate the api-manager.war file to deploy into your application container.

Module Dependency

We do frequent releases so we don't deploy the API Manager artifacts to the Maven Central Repository. This means you must build Monarch from source using SBT and publish the api-manager-common module to your local Ivy repository. By default, this local repository is in ${user.home}/.ivy2/local.

git clone https://github.com/monarchapis/api-manager.git
cd api-manager
sbt "project api-manager-common" publish-local

If you are using Maven (or a derivative such as Gradle or SBT) for your build/dependency management, then you can simply import the module dependency library by pasting one of the below into your project file.

<dependency>
    <groupId>com.monarchapis</groupId>
    <artifactId>api-manager-common</artifactId>
    <version>0.8.3</version>
</dependency>
'com.monarchapis:api-manager-common:0.8.3'
libraryDependencies += "com.monarchapis" % "api-manager-common" % "0.8.3"

Otherwise you can manually reference com.monarchapis.api-manager-common-0.8.3.jar from the lib directory of Monarch.

Security

You are able to create custom Authenticators, Policies, and Claim Sources by implementing the following interfaces (shown below in Scala):

  • com.monarchapis.apimanager.security.Authenticator
  • com.monarchapis.apimanager.security.Policy
  • com.monarchapis.apimanager.security.ClaimSource
package com.monarchapis.apimanager.security

trait Authenticator {
  def name: String
  def displayName: String
  def propertyDescriptors: List[PropertyDescriptor]
  def authenticate(
    keyStore: KeyStore,
    request: AuthenticationRequest): Either[AuthenticationContext, Seq[HttpHeader]]
}

trait Policy {
  def name: String
  def displayName: String
  def propertyDescriptors: List[PropertyDescriptor]
  def verify(
    config: Configuration,
    request: AuthenticationRequest,
    context: AuthenticationContext): Boolean
}

case class Claim(`type`: String, value: String)

trait ClaimSource {
  def name: String
  def displayName: String
  def propertyDescriptors: List[PropertyDescriptor]
  def getClaims(
    config: Configuration,
    request: AuthenticationRequest,
    context: AuthenticationContext): Set[Claim]
}

Analytics

Similar to the security modules above, you may also create custom Event Processors for dealing with analytical data as it is received. This is accomplished by implementing the com.monarchapis.apimanager.analytics.EventProcessor interface which is shown below (in Scala).

package com.monarchapis.apimanager.analytics

trait EventProcessor extends Registerable {
  def process(eventType: EventType, data: ObjectNode, args: String*)
}

Commands

Monarch provides you with very basic command processing (e.g. Logging a message that shows in the admin console) but you can create custom processors for automating tasks inside the system. In a command processor, you have access to the underlying services and functionality that the APIs may not expose. The com.monarchapis.apimanager.command.CommandProcessor trait/interface is used by implementing custom command processors.

package com.monarchapis.apimanager.command

trait CommandProcessor[T] extends Registerable {
  def objectType: Class[T]
  def process(data: T): Any
  def processAny(data: Any): Any = process(data.asInstanceOf[T])
}

Packaging

Package your custom code into a jar and follow the steps above for adding modules to the system. Next, your class needs to be registered in the Spring context configuration. Open conf/context-security.xml and find the Authenticator, Policy, or Claim Source registries. The example below shows a custom authenticator added inside the registry. The order in which the classes are added to the list will determine the order in which they are executed. For Policies and Claim Source, the beans just need to be added outside the registry because they are automatically registered by Spring. The same goes for analytics Event Processors. However, they should be added to conf/context-services.xml.

conf/context-security.xml

<!--
    Authenticator Registry
-->
<bean
    id="authenticatorRegistry"
    class="com.monarchapis.apimanager.security.AuthenticatorRegistry">
    <constructor-arg name="authenticators">
        <list>
            <bean class="com.monarchapis.apimanager.security.HawkV1Authenticator" />
            <bean class="com.acme.api.security.MyCustomAuthenticator" />
        </list>
    </constructor-arg>
</bean>

<!--
    Policy Registry
-->
<bean
    id="policyRegistry"
    class="com.monarchapis.apimanager.security.PolicyRegistry" />

<!-- Add custom policies here -->

<!--
    Claim Source Registry
-->
<bean
    id="claimSourceRegistry"
    class="com.monarchapis.apimanager.security.ClaimSourceRegistry" />

<!-- Add custom claim sources here -->

conf/context-services.xml

<!-- Analytics: Event Processors -->
<bean
    id="analyticsEventProcessorRegistry"
    class="com.monarchapis.apimanager.analytics.EventProcessorRegistry" />

...

<!-- Add custom event processors here -->