Codecademy Logo

Design First API Design

What is YAML?

YAML (short for yet another markup language or YAML ain’t markup language) is a human-readable data serialization language.

doe: "a deer, a female deer"
calling-birds:
  - huey
  - dewey
  - louie
  - fred

YAML Use Cases

Common YAML use cases include configuration files, log files, interprocess messaging, cross-language data sharing, object persistence, and debugging of complex data structures.

YAML vs JSON

YAML and JSON are similar in that they can both store complex data structures that easily transport to other languages. The benefits of YAML include better human readability and features such as comments and referencing other objects in the same document. The main benefit of JSON is that it is more efficient for computers to parse so it can achieve better real time performance.

YAML and Whitespace

In YAML, objects are separated by the use of whitespace (indentation and line breaks). Indentation must consist of spaces; tabs are forbidden. 

transportation:
  planes:
    - Commercial
    - Regional
  - trains:
    - Freight
    - Passenger
  - automobiles:
    - trucks
    - cars
movies: theater
tv: home

YAML Mappings

YAML documents are made up of mappings, or key-value pairs. Keys are separated from values by a colon and space. All keys must be unique, and values can be sequences, scalars, or nested mappings. 

Earth:
  location: 3
  composition: solid
Jupiter:
  location: 6
  composition: gas

YAML Sequences

In YAML, sequences are made up of elements starting with a hyphen and space and separated by line breaks. Alternately, the elements may be surrounded by brackets and separated by commas in a single line. 

numbers:
  - 1
  - 3.14
  - e
birds: [pidgeon, crow, raven]

YAML Scalars

In YAML, scalars include all data types other than mappings and lists. Scalars are strings, integers, floating point numbers, booleans, or null. 

scalars:
  float: 2.1
  integer: 872
  string: abra kadabra
  boolean: True
  null value: null

Code First API Approach

In the “Code First” approach to API development, developers write the code for their API after a business plan has been written. The documentation is then generated based on the code. This approach emphasizes speedy development and is best used for internal APIs.

Previous
0