In a modern, cloud-based environment, a web application is usually a means to an end; the goal is to expose the web application through APIs, so that it can integrate with client applications.

An API-first approach to developing services puts the concerns of the client application developer first. You begin by visualizing your application as a set of services that can be easily consumed by client applications. Complexities in your business logic layer are managed in the service interface and hidden from the client application. This leads to a better developer experience and enables you to add new functionality later on with minimal disruption to existing integrations.

An API-first approach to developing ABL services

API-first development typically consists of the following stages:
  • API planning
  • API design
  • API development
  • API testing

Plan your APIs

  • Identify the types of client applications that require support.Do you have existing client applications that you need to integrate your ABL application with? What types of client applications will require support in the near future? Here are a few types of client applications:
    • REST clients
    • SOAP clients
    • JavaScript Data Object (JSDO) clients
    • ABL clients
    • Open clients (Java, .NET)
  • Determine the types of ABL services you need to create. The types of client applications determine the services that you develop and the PAS for OpenEdge transports that you use.
    Client type Type of service that you need to create PAS for OpenEdge transport
    REST client REST service WEB or REST
    SOAP client SOAP service SOAP
    JSDO client Progress Data Object service WEB or REST
    ABL, Java, .NET - APSV
    To create a RESTful ABL service, you use either the WEB or the REST transport. The WEB transport is the recommended way to develop REST services. It supports all HTTP verbs and content types. Because its service interface—called OpenEdge.Web.WebHandler—is an ABL class, it offers a lot of flexibility in how you handle requests and responses.
  • Identify what data will be exchanged between your services and client applications. This will determine how you build the service interface layer. For example, when a user clicks a Place Order button in a client application's UI, you will want your Order API to pass the order data to a CreateOrder() method in an Order ABL class. There may be other utility classes for emailing the order, doing some XML transformation, etc, that you may not want to include in the Order API.
  • Determine the data format. REST services and clients typically use JSON, SOAP services and clients use SOAP/XML, etc.

Design your APIs

Design the URIs that will be called by the client application. One way to do this is to map endpoints to operations and sample request and response data. Here is an example:
Operation Endpoint Request Response
PlaceOrder OrderService/Order HTTP POST 
{
  "orderid": "123abc",
  "order-date": "1/12/19",
  "order-line": [],
  "shipping": [],
  "billing": []
}
 Status: 200 OK
CancelOrder /OrderService/Order HTTP DELETE 
{
  "orderid": "123abc"
}
 Status: 200 OK
GetOrder /OrderService/Order?order-id={order-id} HTTP GET 
{
  "orderid": "123abc",
  "order-date": "1/12/19",
  "order-line": [],
  "shipping": [],
  "billing": []
}

Develop your APIs

You perform the following tasks to develop your APIs:
  • Set up your OpenEdge project
  • Create services that are bound to PAS for OpenEdge transports
  • Develop service interfaces that are bound to URIs
The topics that follow cover these tasks.

Test your APIs

Before you can test your services, your OpenEdge project needs to be deployed to a PAS for OpenEdge instance as a web application archive (WAR).

Your environment may include a remote PAS for OpenEdge instance that is set up by an administrator. In this case, the administrator may extract ABL artifacts from your source control repository and deploy them to the instance. Alternatively, you can choose to publish the ABL services to a local development PAS for OpenEdge instance from within OpenEdge Developer Studio.