Web API design Methodology--a more complete Web API development process

to be Web design, implementation and maintenance API not just a challenge; for many companies, this is an imperative task. This series will lead readers through a journey, from Identifying business use cases to designing methodologies for the API, addressing implementation challenges, and looking at Maintaining public on the Web over the long term API . There will be interviews with influential people along the way, and even a List of recommended readings for APIs and related topics.

this article InfoQ article is Web API from start to finish article in a series of articles. You can subscribe here so that you can be notified when new articles are published.

The design Web API is more than just URLs, HTTP status codes, header information, and payloads. The process of design-basically for your API to "observe and feel"-is very important and worth your effort. This paper briefly outlines an API design methodology that simultaneously plays both HTTP and web advantages. And it is not only valid for HTTP. If you sometimes need to do the same with WebSockets, XMPP, Mqtt, and so on, the results of most API designs are also available. Enabling future support for multiple protocols is easier to implement and maintain.

Excellent design beyond URL, status code, header information and payload

In general, the Web API Design guide focuses on common features such as URL design, proper use of the HTTP features such as status codes, methods, header information, and payload designs that hold serialized objects or object graphs. These are important implementation details, but not much of an API design. And it is the design of the API-the expression and description of the basic functionality of the service-that makes a significant contribution to the success and usability of the Web API.

An excellent design process or methodology defines a set of consistent, repeatable sets of steps that can be used when outputting a server-side service component as an accessible, useful Web API. That said, a clear methodology can be shared by developers, designers, and software architects to help people work together throughout the implementation cycle. A mature methodology can also evolve over time, refining as each team finds ways to improve and streamline processes without adversely impacting implementation details. In fact, when both the implementation details and the design process are clearly defined and separated from each other, the implementation of detail changes (such as which platform, OS, framework, and UI styles are used) can be independent of the design process.

API Design Seven-step

Next we will briefly outline the design methodology presented in the book "RESTful Web API", co-authored by Richardson and Amundsen. Because of the limitations of space, we cannot delve into every step of the process, but this article will give you a general idea. In addition, readers can use this overview as a guide to develop a unique Web API design process based on the skills and goals of their organization.

Description: Yes, 7 step looks a bit more. There are actually 5 steps in the list that belong to the design, and an additional two entries are implemented and published. The last two steps outside the design process are to provide an experience from beginning to end.

You should plan to re-iterate these steps as needed. Realize that you have more work to do in step 1 (list all the components) by using step 2 (drawing a state diagram). When you're close to writing code (step 6), you might find something missing in the 5th step (creating a semantic file). The key is to use this process to expose as much detail as possible, and be willing to take a step back or two steps to fill in the front missing. Iterations are the key to building a more complete service picture and clarifying how to expose it to client programs.

Step 1: List all components

The first step is to list all the pieces of data that the client program might want to get from our service or to put into our service. We call these semantics descriptors. Semantics refer to what they do with the data in the application, descriptors that describe what happens in the application itself. Note that the viewpoint here is the client, not the server side. It is important to design the API as something that the client uses.

For example, in a simple todo list app, you might find these semantic descriptors:

• ID: Unique identifier for each record in the system
• Title: Titles for each TODO item
• DateDue: the date to which the backlog should be completed
• Complete: A Yes/no flag indicating whether the backlog has been completed.

In a fully functional application, there may also be many semantic descriptors, involving the classification of the backlog (work, home, gardening, etc.), user information (for multi-user implementations), and so on. But in order to highlight the process itself, we will keep it simple.

Step 2: Draw the State diagram

The next step is to draw a state diagram based on the recommended API. Each box in the diagram represents a possible representation-a document containing one or more of the semantic descriptors identified in step 1. You can use arrows to represent transitions from one box to the next-from one state to the next. These transitions are triggered by a protocol request.

There is no need to specify which protocol method to use in each change. Just indicate that the change is safe (such as HTTP GET), unsafe/non-idempotent (such as http.post), or unsafe/idempotent (PUT).

Note: idempotent actions refer to repeated executions without unforeseen side effects. For example , HTTP PUT, because the specification says that the server should use the state value from the client to replace the existing value of the target resource, so that it is idempotent. HTTP POST is non-idempotent, because the specification indicates that the submitted value should be appended to the existing resource collection instead of replaced.

In this case, our client application for this simple to-do service may need to access the list of available entries, filter the list, view a single entry, and mark the entry as completed. Many of these actions use state values to pass data between the client and the server. For example, the Add-item action allows the client to pass the status value title and DueDate. Here is a diagram of the states that illustrate those actions.

The actions shown in this state diagram (also listed below) are also semantic descriptors-they describe the semantic actions of the service.

• Read-list
• Filter-list
• Read-item
• Create-item
• Mark-complete

As you do this, you may find yourself missing out on actions or data items that the client really wants or needs. This is the opportunity to go back to step 1, add some new descriptors, and/or improve the state diagram in step 2.

After you re-iterate these two steps, you should have a good idea of all the data points and actions that the client needs to interact with the service.

Step 3: Harmonic magic Strings

The next step is to reconcile all the "magic strings" in the service interface. The "magic Strings" are all the names of descriptors-they don't have an intrinsic meaning, they just represent the actions or data elements that the client will be accessing when communicating with your service. Reconciling these descriptor names means using public names that are more well-known from the following places:

• schema.org
• microformats.org
• Dublin Core
• IANA Link Relation Values

These are all well-defined, shared name libraries. When your service interfaces use names from these sources, it is likely that developers have seen them before and know what they mean. This can improve the usability of the API.

Note: Although it is a good idea to use a shared name on a service interface, it can be used in an internal implementation (such as a data domain name in a database). The service itself can map the public interface name to the internal storage name without difficulty.

As an example of a to-do service, except for a semantic descriptor-create-item, I can find all acceptable names. For this I created a unique URI based on the rules in the web linking RFC5988. A compromise is required when selecting a well-known name for the interface descriptor. They rarely fit perfectly with your internal data storage elements, but that's fine.

Here is my result:

• ID--Identifier from Dublin core
• Title-Name from schema.org
• DueDate, scheduledtime from schema.org
• Status from Schema.org, complete
• Read-list from the IANA Link Relation values Collection
• Search from IANA Link Relation values, filter-list
• Read-item from the IANA Link Relation values Item
• Create-item, with RFC5988 Http://mamund.com/rels/create-item
• Mark-complete-Edit from the IANA Link Relation values

After the name reconciliation, my state diagram becomes the following:

Step 4: Select a media type

The next step in the API design process is to select a media type that is used to pass messages between the client and server side. One of the features of the web is that the data is transmitted through a unified interface as a standardized document. It is important to choose a media type that supports both data descriptors (such as "identifier", "status", etc.) and action descriptors (such as "Search", "edit", etc.). There are quite a number of formats available.

When I write this article, some of the top hypermedia formats are (in no particular order):

• Hypertext Markup Language (HTML)
• Hypertext Application Language (HAL)
• Collection+json (CJ)
• Siren
• Json-api
• Unified Base for Exchange expressions (UBER)

It is also important to have the selected media type apply to your target protocol. Most developers prefer to use the HTTP protocol as a service interface. However, WebSockets, XMPP, Mqtt, and Coap can also be used-especially for high-speed, short-message, end-to-end implementations.

In this example, I will use HTML as the message format and take the HTTP protocol. HTML has all the necessary support for data descriptors (<UL> for lists, <LI> for entries, <SPAN> for data elements). It also has enough action descriptor support (<A> for secure links, <form method= "get" > For security transitions, <form method= "POST" > For non-security transitions).

Note: In this state diagram, " Edit " the action is idempotent (for example , HTTP PUT ), and HTML still not on PUT native support. In this example, I'll add a field to make the POST of the HTML idempotent.

OK, now I can create some sample representations based on that state diagram to "try" this interface. For our example, only two representations are rendered: to-do list and to-do entries:

Figure 1 : With HTML represents a backlog list collection

Figure 2 : With HTML represents A to-do entry

Remember, when you do a representation of a state diagram, you may find that there are some omissions in the previous steps (such as missing descriptors, power in the action descriptor, etc.). That's okay. Now is the time to solve all of these problems-before you turn this design into code.

When you are completely satisfied with the expression, there is one more step before you start writing the code--Create a semantic archive.

Step 5: Create a semantic archive

A semantic archive is a document that lists all the descriptors in the design, including all the details that help developers build client and server-side implementations. This file is an implementation guide , not an implementation description. This difference is very important.

The format of the service descriptor

The service Description document format has been in place for quite some time and is handy when you want to implement production code or documentation for an existing service. There are many different formats.

When I wrote this article, the top contenders were:

• Web Service Definition language (WSDL)
• Atomic Service Description (ATOMSVC)
• Web Application Description Language (WADL)
• Blueprint
• Swagger
• Rest-style Application Modeling Language (RAML)

Format of the archive

Now there are only a few file formats. We recommend the following two kinds:

• Application-Level semantic archives (ALPS)
• Json-ld + Hydra

These two are relatively new. The JSON-LD specification reached a recommendation in the early 2014. Hydra is still an unofficial draft (or in this article) and has an active developer community. Alps is still in the early draft stage of the IETF.

Because the idea of an archival document is to describe a real-life aspect of a problem space (not just a single implementation in that space), the format is very different from the typical description format:

Figure 3:alps format todo List Semantic archive

You'll notice that this document is like a basic glossary that contains all the possible data values and actions in the to-do service interface-that's the idea. Services that agree to follow this file can decide their own protocols, message formats, or even URLs. The client who agrees to accept this file will be built to be recognizable, if appropriate, to enable the descriptor in this document.

This format is also ideal for generating human-readable documents, analyzing similar files, tracking which files are most widely used, and even generating state diagrams. But that was the subject of another article.

Now that you have the complete descriptor list of the reconciled names, the flagged state diagram, and a semantic archive document, you can begin to prepare the code to implement the sample server and client.

Step 6: Write the Code

At this point, you should be able to give the design documents (state diagrams and semantic files) to the developers of the server and client programs, so that they can begin to implement the specific implementation.

The HTTP server should implement the state diagram created in step 2nd, and requests from the client should trigger the correct state transition. Each representation sent by the service should be in the format chosen in the 3rd step and should contain a link to an archive created in step 4th. The response should contain the corresponding Hypermedia control, which implements the actions that are displayed in the state diagram and described in the archive document. Client and server-side developers can then create a relatively independent implementation and test to see if they are following the state diagram and archive.

With stable and operational code, there is one more step to do: Publish.

Step 7: Publish your API

The Web API should publish at least one URL that always responds to the client-even in the distant future. I call it the "Kanban url"--everyone knows. Publishing an archive document is also a good idea, and a new implementation of the service can link it in the response. You can also publish human-readable documents, tutorials, and more to help developers understand and use your services.

After doing this, you should have a well-designed, stable, accessible service running and ready to use.

Summarize

This article discusses a set of steps for the Web Design API. The focus is on making the data and actions descriptive and documenting them in a machine-readable way so that human developers can easily implement the client and server side of the design, even without direct contact.

These steps are:

1. Lists all the components that collect all the data elements required by the client to interact with the service.
2. Drawing a State graph records all actions provided by the service (state changes)
3. Harmonic Magic Strings Organize your public interfaces to match (as far as possible) well-known names
4. Select the media type review message format to find the one closest to the service transformation of the target protocol.
5. Create a semantic archive write an archive document that defines all the descriptors used in the service.
6. Write the code to share the archive document with the client and server developers, and start writing code tests that are consistent with the file/state diagram and adjust if necessary.
7. Publish your API to publish your Kanban URLs and archive documents so others can use them to create new services and/or client programs.

In your design process, you may find that there are missing elements, need to redo certain steps, and make some compromise decisions. This appears as early as possible in the design process. You may also use this API to design future developers who require new formats and protocols.

Finally, this methodology is just one possible way to create a reliable, repeatable, consistent design process for the Web API design process. When you do this, you may find that inserting some extra steps, or shrinking some, is better, and--of course--The message format and protocol decisions may change in different cases.

Hopefully this article will give you some insight into how to create the best API design methodology for your organization and/or your team.

Web API design Methodology--a more complete Web API development process