How to model (REST) Services APIs
Content
How to model Service Interfaces
When modelling services there is no difference to regular interfaces. As for interfaces all operations of a service including parameters, return type and exceptions have to be defined. In addition the interface has to be marked with the stereotype «JEAFService». Only based on this stereotype JEAF Generator is able to detect a service and then will generate specific code for service interfaces.
For further information please also refer to:
How to model Service Objects
Service Objects define together with service interface (stereotype «JEAFService») the public API of a service. Thereby the services interface define the offered operations of a service. Service objects describe the data than can be exchanged between a service and its client.
As you can see from the example above service objects will be modeled as regular classes with stereotype «ServiceObject». Associations between service objects are modeled according to UML standard.
As described in General Behavior of JEAF Generator access methods for attributes and associations do not have to be modeled explicitly. They will be generated by JEAF Generator by default.
As you can see on class Account from the example it is also possible to define operations for service objects. However we strongly recommend to only define convenience methods on them. It’s considered to be bad style to place real business logic there.
For further information please also refer to:
How to model Enumerations
The example above shows how to model enumerations. As you can see in UML model enumerations have to be marked with stereotype «JEANEnumeration». Also attributes are supported for enumerations.
For further information please also refer to:
How to model Exceptions
JEAF’s concept of exception handling distinguishes between two types of exceptions: application and system exceptions. Application exceptions are used to indicate problems that are connected with the business logic of the application like unfulfilled constraints etc. System exceptions are used to indicate technical problems like not available external services or other technical problems.
As both types of exceptions are also part of the public API of an service they need to be defined in the model. Therefore you can make use of stereotypes «ApplicationException» and «SystemException». Depending on the used stereotype either the one or the other will be generated.
Please be aware that neither attributes nor operations are supported on exceptions. Also Inheritance is not supported. The generated exceptions will the matching JEAF exception class as parent.
For further information please also refer to:
How to model Query Objects
The example above shows an example for a query object. As you can see they are modeled similar to service objects. Also the same rules applies and behavior of JEAF Generator applies to them. Only difference is that they are marked with stereotype «QueryObject».
In addition query objects also allow references to service objects. From a software design perspective it’s recommended that association in this case are always directed from the query object to the service object but not the other way round.
For further information please also refer to:
How to model Load Strategy Objects
The Load Strategy Pattern can be used to optimize the amount of objects loaded and returned by a service. Due to optimized loading in general also the amount of service calls can be reduced.
When using this pattern then a load strategy object has to be passed as additional parameter to a service. This allows a service client to define which associations of returned service objects should be returned as well.
Diagram above shows an example for a load strategy object. As you can see it is marked using stereotype «LoadStrategy». In addition for every association that should be loaded an boolean attribute is defined. As mentioned before this object will be passed on a service call as additional parameter. It’s the responsibility of the service implementation to interpret the load strategy and only load and return the requested data.
For further information please also refer to:
How to model REST Services
In case that JEAF Services should also be provided as REST Resources then some additional information need to be defined.
First of all the service itself needs to be marked as REST Resource by applying stereotype «RESTResource» in addition also all operations that should be accessible via REST need to be marked with stereotype «RESTOperation». As you can see from the diagram above in addition to the stereotypes itself also tagged values for the REST resource and its operations have to be defined. For details about them please refer to the stereotype definitions «RESTResource» and «RESTOperation».
In addition to normal parameters in case of REST it is also possible to receive paramaters from the path (e.g. /doSomething/{id}) or from the http header or as query paramater. For each of these variants stereotypes are defined («PathParam», «HeaderParam», «QueryParam» and «CookieParam»). These stereotype can be applied on the parameters of an REST Operation («RESTOperation»). In addition it is also supported to group sets of parameters together using so called bean parameters.
For further information please refer to:
How to model Identifiable
Stereotype «Identifiable» can be used to mark an object as Identifiable. This means that it can be identified using an ObjectID. The stereotype is intended to be used in combination with stereotypes «DomainObject», «POJO» and «ServiceObject». In case that such kinds of classes will be marked as identifiable then the generated code will respect that.
For further information please also refer to: