About Jahia APIs

  Written by The Jahia Team
 
Developers
   Estimated reading time:

There is multiple type of possible APIs, but some of them are more suitable than others when you have specific needs. By describing what are the specificity of each you should be able to choose wisely the more appropriate to your needs.

GraphQL API

Jahia provide a GraphQL API and the possibility to extends it.

Pros:

  • It’s modular and extendable
  • It’s design to be consumed by client-side application, because you can get all the data you need in one single call
  • It’s graph oriented, so the data structure of your API is well separated, and may compose data coming from different data sources (e.g. different database tables or even different back-end APIs)
  • Only the requested data is fetched, no unneeded data is sent through the network.
  • Jahia provide basic JCR operations for data retrieval and manipulation
  • It’s continuously evolving, Jahia dev is using it for developing the future UI of Jahia so it become more and more complete.
  • Require some knowledge on GraphQL APIs ( design, syntax ), but it’s easy to get into, and a lot of online resources are available.
  • Client-side application have strong client library that allow easy implementation and some extra features like client side caching ( Apollo client is now available in all JavaScript framework )
  • As the protocol is standardized, you get request validation as well as self-documenting APIs out of the box
  • Great tooling for browsing or testing APIs already exists : GraphiQL, GraphQL Playground

Cons:

  • Mostly oriented towards client-side apps. It will be more difficult to call GraphQL for a server-to-server interaction even if I have no doubt that GraphQL client should exist in a lot of programing language by now.
  • Server-side caching technology is younger (but still feasible)

REST API

Jahia provides a JCR REST API and allows to module to provide JAX-RS REST endpoints.

Pros:

  • Allow to design RESTful Web Services
  • RESTful is better than Actions to design API based on clear contracts and documented endpoints
    • Useful for scripts that would need to call the endpoints for automation of certain task ( example: the Jahia module manager expose a RESTful API to manage modules)

Cons:

  • Still not easy to use from client-side application, for similar reasons than the Actions.
    • In case you need to get multiple data you will have to chain multiple HTTP request ( It’s the case of the JCR REST API provided by Jahia, if you need more than one node data )
  • REST is not a “strong” API design model, there are many different ways of doing the same thing.
  • Still puts a lot of burden on the client implementation because as there is no standard REST protocol the clients must implement each REST API calls themselves
  • The response body might contain a lot of unnecessary data and the only way to address this is to build into the REST API a way to specify which object fields are needed or not.

Jahia Actions

Historically Jahia provided the Actions, to be able to create simple API calls based on node path and action name. Full documentation on Actions.

They are still used nowadays mostly for unique calls from client side or external calls.

Pros:

  • Easy and fast to do
  • Useful when you need to do unique calls (like: Adding tag to a content)

Cons:

  • Not suitable for client-side applications
    • Actions do not expose APIs using a standard such as REST or GraphQL
    • Because of the nature of the Actions ( unique logical action per Action class) it will start to be complicated when you need to get multiple informations at the same time, you risk to
      • have complex big Actions that deliver all the informations needed at once, making the Actions complex and not flexible
      • have multiple HTTP calls from the client side to get the complete set of data.
      In both cases it’s not recommended and not suitable for a client-side application.

Custom URLs/Controllers

Jahia also provide the possibility to register Spring SimpleUrlHandlerMapping, by doing so you can map URLs to controllers easily.

That’s how one of our internal test API is exposed, here is a code sample from this module responsible for mapping URLs:

<bean name="jahiaTestMapping" class"org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
	<property name="urlMap">
		<map>
			<entry key="/test" value-ref="testController"/>
			<entry key="/test.html" value-ref="testController"/>
			<entry key="/test/**" value-ref="testController"/>
			<entry key="/createsite" value-ref="testCreateSiteController"/>
		</map>
	</property>
</bean>

So you can map your own controllers to your own URL(s).
You can find a lot documentations on this Spring controllers on the web.

Pros:

  • You can do whatever you want to handle the requests
  • You are using Spring Objects to extends the Jahia Urls

Cons:

  • You have to create everything from scratch by handling the requests and building the responses the old fashion way.
  • Not suitable for client-side usages.

This kind of extension is really the lowest level of request/response handling you can do in Jahia. In some cases it can be useful to expose your own URLs and handle everything without any framework restrictions.

Conclusion

By now you should have a better idea on what type of API you can implement and in which cases it’s better to use one among the others. To summarize:

  • Actions: Used for unique isolated operations, if you need one or multiple simple component(s) that perform a server side action, implement an Action. If you need more complex server side interactions it is recommended to instead consider building a  RESTful or GraphQL API.
  • RESTful API: This kind of API are still common in projects nowadays, the main advantage is the clear API it provides and the fact that the results is easily cacheable. REST is also a good choice when dealing with structured data that require CRUD API to be exposed. But still it’s not as flexible as GraphQL for client-side applications, rapidly changing requirements on the client-side don’t go well with the static nature of REST.
  • GraphQL API: Mostly used by client-side applications ( SPA ), because it’s easy to manipulate and optimized for client-side development. client-side client provide Caching, developer tools, and other tools that will ease you client-side app development and lifecycle. Also the technology is the youngest one, and have been design to address the needs of client-side applications. This isn’t to say it can’t also be used for server-to-server calls either, that’s perfectly acceptable.
  • Custom URLs/Controllers: In case you need to do everything custom, by handling the HTTP request and build the complete HTTP response, you can provide Spring URL handler mappings.

REST and GraphQL have both differents advantages. But the main question you should ask is “How my data need to be consumed ?” 

At Jahia we believe in GraphQL and rely more and more on it.