What is YIZY API?

YIZY API is an opinionated style of building Json API. You've probably heard of Restful APIs, it's a set of rules that governs how your API should be built. YIZY API is also a set of rules that governs how Json API should be built.

What makes an API 'Restful'? I get different answers talking to different engineers. When should a server return a 404 Not Found and not a 200 OK with null in the response body? I am not sure. What I do know is that in my experience, trying to follow Restful convention isn't as restful as the name suggests, so I decided to built my own convention.

YIZY API Convention and Practices

Let's start by violating restful practices 😈

YIZY API Specification

Open API Spec is a very popular format for documenting 'Restful-ish' APIs, YIZY API also has its own specification format. YIZY API Spec is a lean api specification format following YIZY API conventions and practices. It's also a subset of Open API spec which means it can be converted into an Open API Spec easily, just not the other way around. You can write an YIZY API Spec in Typescript with code completion as well as Json and Yaml. I plan on adding a GUI for editing the spec and collaboration easier in the future as well.

import {  type Service,
          field,
          referenceType,
          nullableReferenceType,
          objectType 
       } from '../yizy';

export const secretService: Service = {
	serviceName: 'SecretService',
	baseUrls: ['http://localhost:8080'],
	endpoints: [
		{
			url: '/agents/getAgentByName',
			name: 'getAgentByName',
			requestModel: objectType('GetAgentByNameRequest',
            [
                field('name', 'string')
            ]),
			responseModel: objectType('GetAgentByNameResponse', 
            [
				field('error', nullableReferenceType('Grenade')),
				field('agent', referenceType('Agent'))
			])
		}
	],
	referenceTypes: [
		objectType('Agent', [
			field('name', 'string'),
			field('age', 'int'),
			field('department', 'string')
		]),
		objectType('Grenade', 
                   [
                     field('code', 'int'),
                     field('msg', 'string'),
                     field('name', 'string')
                   ])
	]
};

YIZY Code Generators

One of the most important benefit of having an API spec is that code can be generated to enforce end to end type-safety across the server and the client. Traditional code generators usually requires tedious installation and configuration to get up and running. YIZY API Code Generators takes a different approach. Upload your spec and copy the generated code into your favorite editor with zero configuration! The generator runs in the browser!