About Jahia APIs

October 8, 2024

There are multiple types of APIs that you can use with Jahia. Some are more suitable than others depending on your specific needs. This topic describes the specificities of each to help you choose the most appropriate API for your needs.

Please note that these APIs are protected from unauthorized usage, potential XSS/CSRF attacks and from being called from anywhere. You'll find more details in the Security service and filter documentation.

GraphQL API

Jahia provides a GraphQL API and the ability to extend 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 of data coming from different data sources (for example, different database tables or even different back-end APIs)
  • Only the requested data is fetched, no unneccesary data is sent through the network
  • Jahia provides basic JCR operations for data retrieval and manipulation
  • It’s continuously evolving and Jahia devs use it for developing the current Jahia UI, making it more and more complete.
  • It requires some knowledge of 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 libraries 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
  • You can test your APIs in Developer Tools in Jahia

Cons:

  • Mostly oriented towards client-side apps. It is more difficult to call GraphQL for a server-to-server interaction, even if you have no doubt that GraphQL clients 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 that allows you to create modules that provide JAX-RS REST endpoints.

Pros:

  • Allows you to design RESTful Web Services
  • RESTful is better than Actions for designing APIs based on clear contracts and documented endpoints
    • Useful for scripts that need to call the endpoints for automation of certain tasks (for 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 to Actions.
    • If you need to get multiple data, you must chain multiple HTTP requests (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, and there are many different ways of doing the same thing
  • Still puts a lot of burden on the client implementation. As there is no standard REST protocol, the clients must implement each REST API call themselves.
  • The response body may 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 Actions to enable you to create simple API calls based on node path and action name. For more information, see Actions. They are still used now mostly for unique calls from client side or external calls.

Pros:

  • Easy and fast to do
  • Useful when you need to do unique calls (for example, adding a tag to 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 starts to become complicated when you need to get multiple information at the same time. You risk having:
      • complex big Actions that deliver all the information needed at once, making the Actions complex and inflexible
      • multiple HTTP calls from the client side to get the complete set of data
      In both cases it’s not recommended and is not suitable for a client-side application.

Custom URLs/Controllers

Using the Spring Framework and/or Blueprint in Jahia to declare services and handle services lifecycle and wiring is not recommended and is deprecated starting with Jahia 8.2. Consider using OSGi declarative services instead, you can find examples of implementation in Jahia's OSGI Modules Samples repository.

Jahia also provides the ability 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 instead of the other. To summarize:

  • Actions
    Used for unique isolated operations. If you need one or more simple components 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 is still common in projects now. 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 the CRUD API to be exposed. But still it’s not as flexible as GraphQL for client-side applications and 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 integrate. Client-side libraries provide caching, developer tools, and other features to ease your SPA development and lifecycle. Also the technology is the youngest one, and has 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 does my data need to be consumed ?” 

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