15 min 25 sec · English captions are available from the video controls and start off. To save your place and complete practice, use the learning app.
Read the video transcript
An application receives a neatly organized response about a shop's return policy. It contains a policy identifier, a return window, and an evidence status. Every field is present. The return window says thirty days. The current source says fourteen. The response looks ready for software to use,
but its structure hasn't made its claim correct. This lesson explains how to read the interface and the structured message without mistaking either for proof that the task succeeded. Our route has three parts. First, identify the participants and the operation in an API request. Next, read structured data and
separate its format from its evidence. Finally, inspect access, usage boundaries, errors, and streaming. By the end, you should be able to explain what an interface promises, what a response actually contains, and which important checks still sit outside the format. You will also have a way to
examine current documentation without making a paid call. API stands for application programming interface. It describes how one software component can request information or capabilities from another. The important idea is an agreed way to interact. One component asks for a specified operation, supplies the required input, and receives an output or error.
You don't need to build a complete application to investigate those roles. Begin by naming the requester and the component being asked to do something. In our example, the shop application asks another service for policy information. The customer is using the product, but the application is the software
participant making this particular service request. Distinguishing those roles helps you locate responsibilities. The customer's question, the application's request to a service, and the service's response are related messages. They aren't necessarily the same message, and they don't all cross the same boundary. Different interfaces offer different capabilities. A model provider's API can
accept input and return generated output. A database API can look up a record. A payment service API can check a transaction. One application may use all three, but generated text, a retrieved record, and a transaction status have different meanings. A statement about a payment in generated text does not replace the payment service's actual transaction evidence.
An endpoint identifies a particular address or operation within an interface. Think of the API as describing the available interaction, and the endpoint as locating the particular operation you are examining. In the shop example, we might be looking at a policy lookup rather than a payment-status check. This is a teaching description of the operation,
not a claim about a real provider's address or field names. You must consult that interface's own documentation for those details. For any operation, ask a small set of concrete questions. Who sends this request? What work is requested? Which inputs are required? How is access controlled?
What output or error can return? Notice the last question includes failure. A description that shows only a successful example doesn't tell you how to recognize invalid input, denied access, or an unavailable service. The interface's documented behavior is part of what you need to understand. Pause and distinguish two jobs.
A model service returns a sentence saying, “The transaction is complete.” A payment service offers an operation for checking that transaction. Which interface should you examine for evidence of its actual transaction status? Take a moment to decide, and explain your reason. Examine the payment service's status-checking interface and its actual result.
The generated sentence is content about the transaction. It does not establish the transaction's external state. You still need to understand what the payment result means and which transaction it identifies. The useful habit is to match the requested capability and returned evidence to the job, rather than treating every API response as interchangeable. Now let's read the response itself.
JSON is short for JavaScript Object Notation. It is a common text format for structured data. You can learn to read it without becoming a programmer. Structured means that values are organized in a recognizable arrangement, so software can locate them. It doesn't mean that the values are true. A well-organized container and reliable contents are different things. JSON uses several kinds of values.
A string is text, such as a policy identifier. A number can represent a quantity, such as fourteen days. A boolean represents true or false. The null value is another distinct possibility; it is not the number zero, the boolean false, or a promise that information was found. What null means in a particular field depends on the interface's definition.
A schema can allow or disallow it for that field. An object groups named fields and their values. Our policy response is an example: one field identifies the policy, another gives the return window, and another describes the evidence status. An array is an ordered collection. For instance, an illustrative list of source identifiers
could contain a first item and a second item. The order belongs to the data. We shouldn't assume that it means importance, confidence, or approval unless the interface defines that meaning. A schema specifies the expected structure and types of information. In our illustrative response, policy ID contains text, return window days contains a number, and evidence status contains text.
A schema can require those three fields and those types. It answers questions such as whether a field must exist and what kind of value is allowed there. It doesn't independently inspect a shop's policy and determine how many days the policy permits. Consider three versions of the same response under this example's strict schema. One omits the return-window field.
Another puts the text “thirty days” where the schema requires a number. The third supplies the number thirty and includes the two required text fields. The first two fail this specified structural check. The third can pass it. We are describing this particular schema, not assuming that all services accept, reject,
or convert the same inputs in the same way. There is a useful extra distinction here. Text can be valid JSON while failing a particular schema. A quoted phrase is a legitimate JSON string, but it still isn't a number under our required field type. JSON syntax concerns whether the text is formed as JSON. Schema validation concerns whether that data has
the structure and types expected for this operation. Neither test, by itself, compares the answer with the actual return policy. Let's return to the current source. For this teaching example, the policy identifier is P fourteen, and the source permits fourteen days. Our structurally acceptable response identifies that policy but says thirty days.
The field exists, and its value is a number. The mismatch is factual. We need to compare the returned value with the applicable source. Rearranging the same thirty into a cleaner object won't resolve the discrepancy. The evidence-status field also needs interpretation. Suppose the response labels itself “supported.”
That is a value inside the response, not independent proof that support was checked correctly. Ask what process produced that status and which source and claim it evaluated. Even if the policy identifier refers to an existing document, the document may not support the stated number. Existence of a source and support for a specific claim are separate questions.
Try this checkpoint. A response includes the required policy identifier, a numeric return window of thirty, and the text “supported.” The applicable source permits fourteen days. It passes the example's schema. Has it passed the evidence check for the return window? Pause and identify the comparison that matters.
No. Thirty in the response disagrees with fourteen in the source. The structural pass tells us about fields and types. It doesn't establish that the numerical claim is supported. The evidence-status text cannot overrule that mismatch merely by saying “supported.” A useful report would preserve both observations: the response passed the specified schema, and its
return-window claim failed comparison with the applicable source. Access to a service is another boundary. An API key or another credential helps control that access. A credential is not ordinary example content to paste into a public document or source log. It belongs in an appropriate protected mechanism. When inspecting documentation, identify how authentication is supplied, but don't expose a real credential
to make your notes look complete. Reading an authentication example does not require publishing a working secret. A credential also doesn't make every possible operation or record available. You still need to understand the permissions and conditions attached to the service. This connects to our earlier identity and authorization distinction.
An error about access calls for an access investigation. It is not evidence that the requested information is false, and changing the wording of a model's prompt won't necessarily address the failed permission boundary. Rate limits constrain the number of requests or amount of usage within a period. A quota can impose another usage boundary. For an invented illustration, a service might allow
a certain number of requests during a short window and also have a separate total allowance. The exact units, windows, and reset behavior must come from that service's documentation. Don't assume that a limit counts requests when it actually counts another form of usage. Errors require the same care. Invalid input, permissions, rate limits, an unavailable
service, and internal failures are different categories. A missing required field suggests examining the request against the schema. A permission error suggests examining authorization. A usage-boundary error suggests examining the applicable allowance and documented recovery behavior. An unavailable service or internal failure may need another investigation.
Repeating the same request immediately isn't a universal solution. Record the operation, the observed error or status, and the conditions in which it occurred. Then consult the documented response for that condition. For an operation with external effects, preserve our earlier distinction between a failed response and proof that no action occurred. This lesson is about reading the interface's evidence;
it does not introduce an automatic retry rule. The correct next step depends on the operation, its state, and the service's documented behavior. Streaming changes how output arrives. Instead of waiting for the whole result, the service sends output incrementally. The user may see a beginning sooner. Imagine the return-policy answer appearing
a few words at a time. That can make progress visible, but the beginning isn't the completed answer. The last sentence or structured field may still be missing, and content already displayed can still be incorrect. An application therefore needs to distinguish partial output from completed success. Seeing a fragment of a JSON object doesn't
establish that the complete expected response has arrived. Seeing a finished object still doesn't establish factual accuracy or a successful external action. These are different boundaries: some output received, complete response received, structure accepted, evidence checked, and task outcome established. Streaming doesn't merge them into a single success state. Here is a practical exercise you
can do without making a paid call. Open a provider's current API documentation or a playground that lets you inspect the request description. Find where model selection and input fields are documented. Locate authentication, response fields, usage reporting, errors, and output limits. You are reading the interface and its examples. You do not need to submit a request
or enter a payment method to complete this exercise. Make two columns in your notes: documented and unclear. Record the field names and behavior the provider actually specifies, along with which operation and documentation version or date you examined. If an example doesn't explain a usage limit or an error condition, mark it unclear rather than inventing the answer.
Two providers can both generate text while using different field names, input requirements, limits, and behavior. Similar purpose is not an identical contract. Now try this final checkpoint. Why can a perfectly valid JSON response still fail the task? Look beyond the number in our worked example. Name other kinds of evidence that format alone cannot establish.
Pause and form your answer. Syntax and structure do not establish factual accuracy, permission, relevance, or successful action. Our thirty-day claim can be structurally valid but factually wrong. A response can include information the application wasn't permitted to disclose. It can answer a different question. It can describe an action
without evidence that the action completed. These are distinct possible failures, each needing an appropriate check; we aren't claiming that all occurred in one response. You can now inspect an interface without treating it as a black box. Name the requester, the operation, the required input, the access boundary,
and the possible result or error. Read structured values according to the documented schema. Then ask which facts, permissions, relevance, and outcomes remain unverified. The interface makes communication possible. The surrounding evidence and checks determine what we can responsibly conclude from the returned message. Next, we'll examine technical numbers themselves:
their units, percentages, and denominators. That extends the same habit. A well-formed field is not enough, and neither is an impressive number without its definition. For now, keep the practical question simple: what exactly did this response establish, and what still needs checking?