Tutorial: BuildProfessional Web Services


The Developer allows you to build applications that act as Web or XML Services.

Web Services

A Web Service can be simply described as a "program that uses HTTP to receive a request and issue a reply, using XML as the format of the data". There are several advantages with Web Services:

  • Separation of functionality. In any software solution, the modularization of functionality into "black boxes" makes larger systems easier to build and maintain. A modularized solution allows individual modules to be developed or replaced overtime depending on ever changing requirements.
  • Network protocol. The use of HTTP as the protocol to send information between programs means these modules can communicate on a local system, across a LAN or the Internet. Since the Internet is primarily HTTP traffic, modern network hardware and firewalls will handle this traffic efficiently.
  • Interoperability between environments. A modularized solution using standards like HTTP and XML to communication, allows vastly different types of systems and programming environment to "talk" to each other. This allows developers to use the most capable or available tools to accomplish the task at hand.

The BuildProfessional Developer Repository Service is a good example of a Web Service. When you edit a data dictionary, a request is issued to "Get" the detail of the data dictionary. The repository service reads the data dictionary details and the results are returned in an XML file. The client application, the front-end Developer, display and edits the data dictionary details and submits a "Modify" request back to the repository service. The result is complete separation of the "database" repository functionality from the "editor" functionality.

Defining an XML Service

One of the most important steps in building a Web Service with BuildProfessional is to define the request and reply data. In ideal environments you would define the types of requests that can be made and what to expect in the reply before programming the solutions. Use the following examples when thinking of requests and replies:

Request: What is the price for product 123? Reply: "95.99".

Request: Get the full details and all sales history for the last 12 months for product 123. Reply: All the relevant data from many different tables for product 123.

Request: Rebuild the database indexes. Reply: Done or error occurred.

Request: Send via e-mail the latest sales figures to Bob. Reply: Done or error occurred.

Request: Add the following 2000 new products to the database. Reply: Done, the total number products is now or Error, the following product were not added...

Here are example requests the replies in XML format (request.xml and reply.xml). See BuildProfessional's XML Resources for more examples.

XML Schema

A Web Service should publish its interface, defining exactly what requests and arguments may be supplied and what to expect on the reply. Use XML Schema (XSD files) technology to publish these details. As an example BuildProfessional Developer Service provides a comprehensive set of schema files to validate repository requests (see the XML Schema or human readable version or documented version).

Request Validation

If the services publishes a schema, the XML service can simply then reject a request that does not comply to the published xml schema. Since the schema is published and the caller can use local functionality to detect why a request is not valid against the schema, the xml service does not need to provide more details than simply that the request is not valid. This significantly reduces the amount of error handling code required in the xml service.

Once the request is received and it is valid, then the service will still need to apply certain validations and appropriate error descriptions. However the better the xml schema, the less code is required in the service.

Building the XML Service

See the following tutorials to build and access a BuildProfessional Web Service:

Building a Web Service

Building a Web Service Client

Building a Web Application