Access to add and change pages is restricted. See: https://cwiki.apache.org/confluence/display/OFBIZ/Wiki+access

Authentication

API endpoints are authenticated via JWT.

To obtain a JWT token, submit an HTTP request to the following endpoint:

Endpoint: /rest/auth/token

Authentication: HTTP Basic Authentication, requiring an HTTP header in the format:

Authorization: Basic <Base64 encoded "username:password">

For example, to authenticate with username admin and password ofbiz, first Base64 encode the string admin:ofbiz to obtain YWRtaW46b2ZiaXo.

NIX command for encoding:

echo -n "admin:ofbiz" | base64

Example request using cURL:

curl -k -X POST "https://localhost:8443/rest/auth/token" \
-H "accept: application/json" \
-H "Authorization: Basic YWRtaW46b2ZiaXo"

Example response:

{
  "statusCode": 200,
  "statusDescription": "OK",
  "successMessage": "Token granted.",
  "data": {
    "access_token": "<THE JWT>",
    "token_type": "Bearer",
    "expires_in": 1800
  }
}


Use the obtained JWT for all subsequent API calls by adding the following header:

Authorization: Bearer <THE JWT>

Token Expiry: By default, the JWT expires in 1800 seconds (30 minutes). You can modify this by changing security.jwt.token.expireTime in framework/security/config/security.properties. Example:

security.jwt.token.expireTime=2592000  # 30 days

Endpoint Implementation

Dynamic Endpoints: Invoking an Existing OFBiz Service

To expose an existing OFBiz service as an API, set the following attributes in the service definition:

export="true"
action="GET" or  "POST"

Once configured, the service can be accessed via:

/rest/services/{service_name}

Input Parameters:

  • For POST requests: Provide parameters in the request body as a JSON object.
  • For GET requests: Include parameters as a JSON object inside the inParams query parameter.

Example Request:

curl -k -X GET "https://localhost:8443/rest/services/findProductById?inParams=%7B%22idToFind%22:%22GZ-1001%22%7D" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <THE JWT>"

Decoded inParams:

{"idToFind":"GZ-1001"}

Endpoints Implemented as Standard JAX-RS Resources

Endpoints can be implemented as Java classes using the JAX-RS standard.

Annotations:

  • @Secured: Ensures JWT authentication.
  • @ServiceRequestValidator: Validates input parameters against the OFBiz service definition.

Accessing OFBiz Services in JAX-RS:

@Context
private ServletContext servletContext;

LocalDispatcher dispatcher = (LocalDispatcher) servletContext.getAttribute("dispatcher");
Delegator delegator = (Delegator) servletContext.getAttribute("delegator");

Class Registration: Add the package to org.apache.ofbiz.ws.rs.core.OFBizApiConfig for discovery.

Example:

@Path("/jobs")
@Secured
@ServiceRequestValidator
public class ManufacturingResource {

    @Context
    private ServletContext servletContext;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Response jobList() throws GenericEntityException {
        LocalDispatcher dispatcher = (LocalDispatcher) servletContext.getAttribute("dispatcher");
        Delegator delegator = (Delegator) servletContext.getAttribute("delegator");

        List<GenericValue> list = EntityQuery.use(delegator).from("WorkEffort").queryList();

        Success success = new Success(Response.Status.OK.getStatusCode(),
                Response.Status.OK.getReasonPhrase(),
                Response.Status.OK.getReasonPhrase(), list);

        return Response.status(Response.Status.OK).type(MediaType.APPLICATION_JSON).entity(success).build();
    }
}

Endpoints Defined via XML

RESTful APIs can also be defined using XML files following rest-api.xsd. These XML files must:

  • Be located in the api directory inside an OFBiz component.
  • Be named <component-name>.rest.xml.

Example:


party/api/party.rest.xml in party module (before commit #8a31d2f)

<api xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="https://ofbiz.apache.org/dtds/rest-api.xsd"
    name="Party Rest API" publish="true">
    <resource name="party" path="/party" auth="true">
        <!-- Get all parties -->
        <operation action="get">
            <service name="findParty"/>
        </operation>

        <!-- Create a new party group -->
        <operation action="post">
            <service name="createPartyGroup"/>
        </operation>

        <!-- Get party by ID as a sub-operation -->
        <operation action="get" path="/{idToFind}">
            <service name="findPartiesById"/>
        </operation>
    </resource>
</api>



party/api/party.rest.xml in party module (after commit #8a31d2f)

<api xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="https://ofbiz.apache.org/dtds/rest-api.xsd" 
    path="party" name="Party Rest API" publish="true">
    <resource name="party" path="party" auth="true">
        <!-- Get all parties -->
        <operation action="get">
            <service name="findParty"/>
        </operation>

        <!-- Create a new party group -->
        <operation action="post">
            <service name="createPartyGroup"/>
        </operation>

        <!-- Get party by ID as a sub-operation -->
        <operation action="get" path="{idToFind}">
            <service name="findPartiesById"/>
        </operation>
    </resource>
</api>

Swagger Documentation 

To view api swagger documentation 

https://localhost:8443/docs/swagger-ui.html


Miscellaneous Notes

Dependencies:

  • Jersey (JAX-RS implementation) and Jackson (JSON mapping) - Version 2.40
  • Swagger (API documentation) - Version 2.2.20
  • No labels