[PHP] [API] Chapter 6:api Design

This chapter marks a turning point in the course of our understanding of APIs. We have already learned the components and now we will learn how to combine concepts to form an API. In this chapter, we will explore the components of the API by designing an API.

Organization data

National Geographic predicts that in 2011, Americans will take 8 billion photos. With such a large number of photos, you can imagine everyone using different ways to organize these photos. Some people like to put everything in a single folder. Some people sort by the hierarchy of the year, month, and event's folder.

Companies also have similar ideas in the organization when they build their APIs. As we mentioned in the first chapter, the purpose of the API is to make the computer and the company's data easy to match. Obviously, a company can decide to use a single URL for all the data and make it easy for them to search (like putting all your photos into a folder). Another way, each data has its own URL, in the hierarchy organization (just like the photo has its folders and subfolders). Each company chooses the best way to build their API in response to different forms, guided by existing industry experience.

Choose a form to start

When discussing APIs, you may hear the word "soap" and "Rest," and wonder if the developer is working or planning a vacation. The fact is that these are the names of the two common architectures for Web-based APIs. SOAP (acronym abbreviation) is an XML-based design that has a standardized structure to request and respond. REST, representing representational transfers, is a relatively open source, providing a large number of contracts, but leaving many areas that need to be discussed in the design API.

Through this course, you may be mainly to our preference for REST APIs. This preference is most of the time, because REST takes incredibly fast. This is not to say that SOAP is evil and that it has its advantages. Still, the focus of our discussion is on rest, because that's the API you'll probably meet. In the remainder of the section, we will understand the components by making a REST API.

Our first resource

Recalling the 2nd Chapter, we talked a little bit about resources. Recall that resources are the nouns of the API (Customer and pizza). These are things that we want the world to interact with through the API.

To feel how a company is starting to design the API, let's try to contact our pizza shop.

For the client to be able to connect with the pizza shop, we need to do a few things:

1. Decide what resources are available.
2. Assign URLs to these resources.
3. Determine what actions clients should be able to do with these resources.
4. Find out what data is needed for each step and what format they should be.

Getting the resources is the first difficult task. One way to solve this problem is to gradually perform typical interactions. For the pizza shop, we may have another menu. On the menu is a variety of pizzas. When the customer wants us we do one of the cakes, they need to place an order. In this context, menus, pizzas, customers and orders sound a good resource. Let's start with the order.

The next step is to assign these URLs to the resource. There is a lot of Ken, but fortunately REST is agreed to give some support. In a typical REST API, the resource will be assigned two URLs. The first is the complex number of the name of the resource, such as/orders. The second is the plural of the resource name plus a unique identifier specifying a single resource, such as/orders/ , which is a unique identifier for a command. These two URL patterns make up our API to support the first endpoint. These are called endpoints, just because they are placed at the end of the URL, such as http://example.com/ .

Since we have selected resources and assigned URLs, we need to decide what actions the client can take to execute. Based on the convention of REST, we can know that the plural endpoint (/orders) is used to list existing orders and to create new ones. An endpoint (/orders/) with a unique identifier that is used to retrieve, update, or cancel a particular order. The client tells the server what actions (GET, POST, PUT, DELETE) will be transmitted over the HTTP channel in the request.

In short, our API now looks like this:

| HTTP Verb | Endpoint | Action |

| ——— | ——— | ———————— |

| GET | /orders | List Existing orders |

| POST | /orders | Place a New Order |

| GET | /ORDERS/1 | Get details for Order #1 |

| GET | /ORDERS/2 | Get details for Order #2 |

| PUT | /ORDERS/1 | Update Order #1 |

| DELETE | /ORDERS/1 | Cancel Order #1 |

To enrich the action of our order endpoint, the final step is to determine what data needs to be exchanged between the client and the server. Borrowing from our example in the 3rd chapter of the pizzeria, we can say that an order requires a crust of bread and a variety of fillings. We also need to select the data format for passing information between the client and the server. Both XML and JSON are good choices, but for readability, we choose JSON.

At this point, you have designed a functional API. Here's how the client and server interact with the API:

Connect the resources together

Our pizza shop's API looks sharp. Orders come in in an unprecedented way. In fact, the business is very good, we decided to start to follow the customer's loyalty to track orders. A simple new way to do this is to add a new customer resource.

Just like orders, our customer resources require a certain endpoint. As the following convention,/customers and/customers/ very good wedge together. We skip these details, but we assume that each of our actions adds meaning to each endpoint and which data represents a customer. Assuming we do everything, we have another interesting question: How do we make orders and user discovery contact?

REST practitioners are obsessed with how to solve problems associated with resources. It is said that the hierarchy should continue to increase, increasing the endpoint like/customers/5/orders refers to the fifth customer's order,/CUSTOMERS/5/ORDERS/3 refers to the fifth customer's third order. Others think it should make things easier by getting more information about a data. In this mode, order custonmer_id can be created with order information. Both of these are quite extensive in the use of REST APIs, so it's worth knowing.

Search data

As one system data increases, it becomes impractical for endpoints to list all of the records. Imagine if our pizzeria has 3 million completed orders, you want to know how many toppings for pepperoni. Sending a GET request to/orders and receiving all 3 million orders will become useless. Fortunately, REST has an excellent way to search for data.

The URLs have a component that we didn't mention, query Sting (Inquiry string). A query refers to the text of a search and a string representation. The query string is some text that goes to the end of a URL, passing information through a URL. For example, the information after the question mark is query data: Http://example.com/orders?key=value.

The REST API uses query strings to define the details of the search. These details are called query parameters. The API determines what parameters it will receive, and the search needs to be implemented with these exact names. Our pizza shop API allows clients to search for orders via Url:http://example.come/orders?topping=pepperoni. The client can also query by listing a parameter, separated by a symbol ("&") and querying multiple parameters. For example: Http://example.com/orders?topping=pepperoni&crust=thin.

To limit the number of data returned in each request when querying for another use of the string. Typically, the API divides the results into groups (100 or 500 of records) and returns a group within a single time. The process of splitting up the data is called paging (metaphorically composing the words into a page). Allows the client to scroll through all the data, and the API will support query parameters that allow the client to pin the data page it wants. In our pizza shop API, we can allow customers to specify two parameters: page and size by supporting paging. If the client makes the request like get/orders?page=2&size=200, we all know that they want the result to be the second page, 200 results per page, order 201-400.

Sixth Chapter Summary

In this section, we learned how to design a REST API. We found the basic functionality that the API supports and how to organize the data so that it can be easily absorbed by the computer.

The key points we know:

• SOAP : An information format that standardizes the API architecture.
• REST : Controls the API architecture of the Resource Center.
• Resource : A noun for an API project is like a customer and an order.
• Endpoint : The URL that forms part of the API. In REST, each resource has its own endpoint.
• Query String : Part of the URL used to pass data to the server.
• Query Parameters : The value found in the query string (Topping=cheese).
• pagination : The process of separating the structure into the management module.

