From 2dd66db90a2574a106c3d2b36d78c55a5ab48474 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Mon, 19 Mar 2018 21:34:35 +0000 Subject: [PATCH] Updates to JSON Introduction (#162) * Updates to JSON intro * Fix link, remove callout annotation * Update json-introduction.md --- articles/modeling/json-introduction.md | 78 +++++++++++++++++++------- 1 file changed, 58 insertions(+), 20 deletions(-) diff --git a/articles/modeling/json-introduction.md b/articles/modeling/json-introduction.md index d31421f..cd537ac 100644 --- a/articles/modeling/json-introduction.md +++ b/articles/modeling/json-introduction.md @@ -1,25 +1,63 @@ -# Introduction to Objects in API Document Structure +# Introduction to JSON -- An OpenAPI document is a document that describes an API and conforms to the OpenAPI Specification. These documents can be in YAML or JSON format. -- Your OpenAPI document can be a single document or a combination of several associated resources which use the $ref syntax to reference the interrelated resources. +## What is JSON? -## Primitive Data Objects Supported in an OpenAPI Document +JSON (short for JavaScript Object Notation) is a syntax used to represent data +structures in a simple, easy-to-read textual format. JSON is ubiquitous +throughout the computing industry, and has become the de-facto data format of +the Web. -- integer (int32 and int64) -- number (float and double) -- string -- byte -- binary -- boolean -- date -- dateTime -- password +If you have never seen JSON before, here is a small demonstration using JSON to +describe a (fictional) person: -## Additional OpenAPI Objects +```json +{ + "firstName": "Lando", + "lastName": "Calrissian", + "title": "Baron Administrator", + "address": { + "streetAddress": "123 Betrayal Dr", + "city": "Cloud City", + "planet": "Bespin" + }, + "homeworld": "Socorro", + "currentLocation": null +} +``` -- **Info Object**: describes the API's title, description (optional), and version metadata. It also supports other details such as contact information, license, and terms of service. -- **Server Object**: identifies the API server and base URL. You can identify a single server or multiple servers and describe them using a description field. All API paths are relative to the URL of the server, for example, "/pets" when fully dilineated, may describe "http://api.hostname.com/pets." -- **Paths Object**: outlines relative paths to individual endpoints within your API and the operations or HTTP methods supported by the endpoints. For example, "GET/pets" can be used to return a list of pets. -- **Parameter Object**: describes a single operation parameter. Operations can have parameters passed through by several means such as: URL path, query string, cookies, and headers. Parameters can be marked as mandatory or optional, you can also describe the format, data type, and indicate its depreciation status. -- **Request body object**: describes body content and media type. It is often used with insert and update operations (POST, PUT, PATCH). -- **Response object**: describes the expected response which can be referenced using the $ref syntax or described within the document. It associates an HTTP response code to the expected response. Examples of HTTP status codes incldue the 200-OK or 404-Not Found codes. [Click here for more information on HTTP Response codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). +## Why JSON? + +There are many benefits to using JSON, some of which include: + +* It can be used to represent a wide array of objects in a simple and + easy-to-read format, making it useful for just about anything + +* It is widely used and supported across web browsers and programming languages, + making it very easy to develop for + +* It is easy to read and write by humans (as well as computers), making it a + great choice for specifications like [OpenAPI](https://github.com/OAI/OpenAPI-Specification#the-openapi-specification) + +* It is a subset of another syntax called + [YAML](https://en.wikipedia.org/wiki/YAML). Documents written in JSON can also + be written in YAML, so either format can be used to write OpenAPI documents + +* It can be used to link files together through [JSON + references](/modeling/introduction/modeling-with-openapi/referencing-another-api-spec), making it easy to break up large documents + into smaller, more focused documents + +Whether you are modeling an API, creating a Prism Collection, or writing +documentation in Stoplight, behind the scenes you are actually updating a JSON +document. + +> You can see the underlying JSON document of any object being updated in +> Stoplight using the editor's **Code** button at the top of the screen. + +--- + +**Related** + +* [JSON Overview - Wikipedia](https://en.wikipedia.org/wiki/JSON) +* [YAML Overview - Wikipedia](https://en.wikipedia.org/wiki/YAML) +* [OpenAPI Specification Format Reference](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#format) +* [Referencing Another API Specification](/modeling/introduction/modeling-with-openapi/referencing-another-api-spec)