Web|web Services | interactive
Architecture Web Service: Interactive interface, core of Web services definition
Content:
API Overview
Catalog Service
Member Service
Feedback Service
Order Service
Description and Registration: Publishing Web Services
Resources
Author Introduction
Related content:
Real-combat Web services
Web services based applications, solutions, and development platforms
What is a Web service?
Why do I need a Web service?
Chai Xiaolu (fennivel@uddi-china.org)
Chief System Architect
September 17, 2001
This article is the fifth of a series of articles on architecture Web services, based on the application example described above, defines the API message for the catalog service in detail, using SOAP to complete the invocation and return, and this article, through the specific definition of the API, This paper introduces and demonstrates the definition methods and patterns of interactive data structure and API message structure, and provides examples for readers in defining their own Web service interfaces.
In the previous article in this series, a systematic analysis of the given case and a modular division of the system are initially defined as the following online service components:
Catalog Service-Category (Category) management, product management, data exchange, data backup, etc.
Order service-Accept orders, send orders to other services that accept orders, etc.;
Feedback Service-Feedback information (Feedback) management, data exchange and so on.
Because these services obviously must have a user system to support, whether it is because of security considerations (the ability to do certain operations, or because of the user dependencies of the transaction (obviously the order is not likely to be implemented by a service that is out of the user). So we need to add an online service member Service,membership's application can basically rely on processes other than Web services to complete, such as Web application, so the member Service Web The service interface can be fairly simplified. All of these online Component Services need to provide the external interface, our detailed definition starts from the following figure:
Figure 1. API messages
The resources cited in this article mainly include two categories, one is the Web Services Technical Resources Web site, contains a large number of Web services technical information, the other is the Web services "stack" series of technical specifications, they are a whole technical system, including UDDI, SOAP, WSDL, XML and so on. At the end of this article, the links to these resources are given, and interested readers can find what they need through these resource links.
API Overview
For the entire system API design, its following principles have such a few:
Simplicity, because this is a public open Web service, its API design should first of all be simple, to be accepted by a large number of users, to obtain a better application, then the API must be simple, there is no complex and difficult to use the API will be widely accepted, unless the system is too wide coverage, The Web service we are designing now is the new system, so the API has to be simple for the current application reality.
scalability, as newer, more open Web services, the API should have a good backward scalability, when the need for internal changes in demand or external requirements, the API will change according to the new business logic, the API should not be fundamentally overturned reconstruction, You should have an incremental scalability capability.
compatibility, in fact, compatibility and scalability is interoperability, API compatibility refers to backward compatibility, the high version of the API should have the compatibility of the lower version API, that is, the use of the high version of the API Web services, should be able to support the use of the low version API calls.
Efficiency, the API should take into account the simplicity of the premise, the consideration of high efficiency, when some of the combination operation is very frequently used, we should be for such a combination of operation call to design a single portal call only one interaction, which can enhance the efficiency of external applications, while reducing the load of Web services.
Completeness, the so-called completeness means that the entire API to cover all the needs of external disclosure of functions, which is relatively best to achieve the goal, as long as the design phase is fully considered, can achieve the requirements of completeness. It is also relatively easy to fix if an incomplete situation is found.
Catalog Service
Save_category: Save category, which includes updates and new operations in this API call, while category migrations can be done through this API.
Delete_category: Deletes the category, removes the specified category and all its child elements from the catalog.
Find_category: In catalog to find category, you can use a variety of ways, such as the name, such as keywords.
Save_product: Save product, in this API call, you can also include updates, new, and migrated operations.
Delete_product: Deletes the product and removes the information for the specified product from the catalog.
Find_product: Locating product in catalog can be done in a variety of ways, such as name, category, such as keywords.
Get_categorydetail: Gets complete information about category, including summary information and product details for all category that are included.
Get_productdetail: Gets the complete information for product.
Get_categoryinfo: Get all the information about category and all its descendants category and product.
Before defining these messages, we first need to determine the XML description format for both the category and product entities. Referring to the entity Relationship model in the previous article, we can define them as follows:
Category specific description format:
<category categorykey= "..." parentcategorykey= "...". >
<name>......</name>
<description>......</description>
</category>
The specific description format of product:
<product productkey= "..." parentcategorykey= "...". >
<name>......</name>
<description>......</description>
<compliantspecbag/>
<featurebag/>
<parameterbag/>
</category>
The specific formats of Compliantspecbag, Featurebag and Parameterbag are as follows:
<compliantSpecBag>
<specification specificationkey= "..."/> *
</compliantSpecBag>
Compliantspecbag describes a computer product that follows the relevant industry standards. In this gathering, specification this element can occur multiple times, each entry indicates that it follows an industrial standard, such as an entertainment laptop computer may follow industrial specifications such as USB1.0, IEEE1394, etc.
<featureBag>
<feature>......</feature> *
</featureBag>
Featurebag describes an important feature of a computer product. Within this aggregation, feature this element can occur multiple times, and each entry uses string literals to describe a product feature. An entertaining laptop, for example, might feature a description of features such as "weighs only 2 pounds and is 1.9cm thick and super portable."
<parameterBag>
<parameter> *
<keyName>......</keyName>
<keyValue>......</keyValue>
</parameter>
</parameterBag>
Parameterbag describes the technical parameters of a computer product. Within this aggregation, parameter this element can occur multiple times, and each entry uses a KeyName and KeyValue name value pair to describe a technical parameter. For example, the possible technical parameters of a portable computer will be tft_size10.1 ".
After defining the core data model, we can define the specific API messages separately.
Save_category
Used to save the latest information about category, which can be used to perform updates, new, and migrated operations on category.
<save_category>
<authInfo>......</authInfo>
<category categorykey= "..." parentcategorykey= "..." > *
<name>......</name>
<description>......</description>
<category/> *
<product/> *
</category>
</save_category>
In the syntax described above, you should be able to find that save_category can be used to save one or more complete category trees, rather than just preserving one or more category nodes, this design is an adjustment for efficient design goals.
When any category or product in the entire message has a key value Categorykey or ProductKey that identifies its own entity, it means that this is a new category or product that needs to be inserted into the database, and in the return message, The key values for these elements will be echoed.
When any category or product Parentcategorykey in a message does not change, it indicates that the information for the element is being updated. And if the Parentcategorykey changed, Indicates that the element will be migrated from the previous category node identified by the original Parentcategorykey to the category node identified by the new Parentcategorykey. Of course, if a data update operation is included, the data update operation is also implemented.
The attentive reader must have found out in this message, there is a authinfo element, which is an authorization token for the permission test. At a later point I will indicate how this element was fetched and used.
The return of a save_category message invocation is one or more complete accepted category information, and the difference with the submitted information is that there is only an outline information, no information is believed, and the previously empty key value is filled in with the key value assigned by the Web service. The following is an example of a return message:
<result>
<category categorykey= "A01" parentcategorykey= "...". >
<category categorykey= "A02" parentcategorykey= "A01"/>
<category categorykey= "A03" parentcategorykey= "A01"/>
<category categorykey= "A04" parentcategorykey= "A01"/>
<product productkey= "P01" parentcategorykey= "A01"/>
<product productkey= "P02" parentcategorykey= "A01"/>
</category>
<category categorykey= "B01" parentcategorykey= "...". >
<category categorykey= "b07" parentcategorykey= "B01"/>
<category categorykey= "B08" parentcategorykey= "B01"/>
<product productkey= "p09" parentcategorykey= "B01"/>
</category>
</result>
Delete_category
An API call to remove category that can remove one or more category and all its child elements from the catalog.
<delete_category>
<authInfo>......</authInfo>
<category categorykey= "..."/> *
</delete_category>
In the syntax described above, you should be able to discover that save_category can be used to delete one or more category that use Categorykey identities. When a category is deleted, all its child elements, including category and product child elements, are deleted.
The return of a delete_category message invocation is a list of key values for one or more category messages that have been implemented for deletion.
Find_product
Used to search for product in a catalog that satisfies a specified condition, and in this API message, it supports a variety of queries, such as names, according to the industry specifications followed.
<find_product>
<authInfo>......</authInfo>
<category categorykey= "..."/>
<name/>
<compliantspecbag/>
<parameterBag>
</find_product>
In the FIND_PRODUCT message, four search criteria are supported:
Category, this element describes the root of the category subtree to be searched. Indicates that the space for the search to be performed consists of all the child elements of the category identified by the Categorykey in the element.
Name, the string described in this name element exists as the leftmost substring of the name string. The least-left match is implemented in the search, such as "China" as described in the name element, "China" and "Chinese computer" will be matched, and "premium Chinese cars" will not be matched.
Compliantspecbag, which describes the aggregation of an industry specification, depending on the aggregation specified during this search, we can exclude all computer products that do not conform to these specifications from the search result set. For example, the element contains two specifications USB1.1 and IEEE1394, and only products that support both specifications will be searched.
Parameterbag, this element describes the aggregation of a technical parameter that is used in a manner similar to that of Compliantspecbag, and that all computer products that do not conform to the specification specified in the described technical parameters will be excluded from the search result set.
For Compliantspecbag and parameterbag, the processing behavior in the default search is logical, and we can define the logic or the way by parameter designation. For example:
<compliantSpecBag>
<logicbehavior value= "OR"/>
<specification specificationkey= "key[usb1.1]"/>
<specification specificationkey= "key[ieee1394]"/>
</compliantSpecBag>
This example indicates that the computer product that needs to be searched is either compatible with USB1.1 or compatible with the IEEE1394 interface, and that computer products that do not support either specification in either specification will be excluded from the search result set.
The return of the FIND_PRODUCT message invocation is one or more product information that is matched to, but the change information list is a list of the profiles. The following is an example of a return message:
<result>
<product productkey= "P01" parentcategorykey= "A01"/>
<name>......</name>
<description>......</description>
</product>
<product productkey= "P02" parentcategorykey= "A01"/>
<name>......</name>
<description>......</description>
</product>
</result>
After analyzing the above three API messages, it is not difficult to understand that save_product, delete_product and Find_category and the preceding three messages are basically similar and simpler in form, so they are not detailed and waste space.
For the remaining three messages: Get_categorydetail,get_productdetail and Get_categoryinfo, one of these three messages is relatively simple, the incoming key value returns the entity information, second, after the previous demo, I believe you should have a specific understanding, so here is no space to define specific information.
Member Service
For member service, two API messages are available:
Get_authtoken
Used to request an authentication token from the member service. Authentication tokens are required when all other APIs are invoked. This function is functionally equivalent to the program that completes the logon request.
<get_authtoken generic= "2.0" xmlns= "URN:UDDI-ORG:API_V2"
Userid= "Someloginname"
password= "Somepassword"/>
The UserID parameter must appear to represent the individual users authorized by the online service. The Member service provides a method of checking the user ID and password that the user provides. The password parameter must appear, which represents the password for the user ID.
Discard_authtoken
Used to notify the member Service that the previously provided authentication token is no longer valid. When the other Web service receives this message from the member service, the authentication token is still in use, and other Web services should be judged illegal.
<discard_authtoken generic= "2.0" xmlns= "Urn:uddi-org:api_v2" >
<authInfo/>
</discard_authToken>
Authinfo This parameter is required, it is an element that contains the authentication token. Authentication tokens can be obtained by using the Get_authtoken API call.
Feedback Service
Save_feedback: Save feedback, which includes updates and new operations in this API call, while category migrations can be done through this API. In addition, the use of this API can also complete the deletion of the operation (because the reason is designed because the deletion is a last resort action), delete operations by passing in only Feedbackkey and authinfo to complete the operation.
Find_feedback: Locate the feedback in the catalog, such as the name, such as Categorykey.
Get_feedbackdetail: Gets detailed information about all feedback in a category layer.
Get_feedbackinfo: Gets detailed information about all the feedback in the entire subtree under category.
Order Service
Request_order: The order request is issued, which includes two actions to request new orders and cancel orders. When the incoming Orderkey is empty and contains other details, the new order operation is requested. If the incoming Orderkey is the key value of an existing order, and does not contain other details of the ordering, then it is considered an operation to cancel orders. The return of the message can indicate, respectively, the acceptance or rejection instructions for the order request.
Get_orderdetail: Gets the details of the order for later reference.
Find_order: Search for related orders according to the conditions specified in the input parameters.
Description and Registration: Publishing Web Services
In this article, we describe and explain in detail how the API for Web services is designed and defined, and introduces some basic design and application patterns. In the articles that follow this series, I'll end this series with a description of the Web service using WSDL and the use of UDDI to register Web services.
Resources
Web Service Technology/Comment website
Uddi-china.org, a UDDI-oriented Web services technology Web site.
webservices.org, Web Services Integrated class technology Web site.
IBM Developerworks/web Service Zone, IBM's WEB Services technology Resource Center
MSDN Online Web Services Developer Resources, Web Service Developer Resource Web site for Microsoft
Itpapers/web service, Itpapers's WEB Services review article
Interop Stack Series technical standard specification for addressing business-to-business e-business application interactions and integrations
UDDI Executive White Paper, uddi-china.org, uddi.org
UDDI Technology white Paper, uddi-china.org, uddi.org
UDDI Programmer API Specification, uddi-china.org, uddi.org
UDDI data structure Reference, uddi-china.org, uddi.org
Web Service Description Language (WSDL) 1.0, IBM, SEP 2000
Soap:simple Object Access PROTOCOL Specification 1.1, IBM, Microsoft, DevelopMentor, 2000
Extensible Markup Language (XML) 1.0 (Second Edition), the Consortium, 6 OCT 2000
Author Introduction
Chai Xiaolu: Shanghai Easy e-commerce Technology Co., Ltd. (dealeasy) chief System Architect, XML technical advisor. Member of Uddi-china.org Blue Blaze Studio. UDDI Advisor group member, Wsui Working group member. He received a master's degree in computer Science from Fudan University in 2000, and has been in the International Computer Science Conference (ICSC), Asia-Pacific XML Technology Symposium (XML asia/pacific ' 99), China XML Technology Symposium (Beijing), and computer scientific periodicals. Many papers have been published in major domestic conferences and periodicals. specialize in xml-based system integration and data exchange technology research, at the same time, database, object-oriented technology and CSCW technology is better.
