Mock REST API typings and cheat sheet

api.md

API

• download: https://github.com/ducin-public/itcorpo-api
• powered by: https://www.npmjs.com/package/json-server

---

example install script

cd src
git clone https://gist.github.com/ducin/7df11e9fdf362386cbefb5faf4c00c66 typings

# (UNIX) removing git trash (avoiding git submodules)
rm -rf typings/.git
rm -rf typings/api.md

# (Windows) removing git trash (avoiding git submodules)
del typings\api.md
rmdir typings\.git
# or
rd /s typings\.git

---

resources:

• geo: http://localhost:3000/geo
• offices: http://localhost:3000/offices?country=Germany
• employees: http://localhost:3000/employees?office_like=Germany, http://localhost:3000/employees?nationality=DE
• projects: http://localhost:3000/projects/852b697f-1d11-4cfd-ab26-5aa2f926e79d
• benefits: http://localhost:3000/benefits?country=Germany

json-server-based API features:

• collection (first page, limited): http://localhost:3000/employees
• certain page: http://localhost:3000/employees?_page=2
• only total count: http://localhost:3000/employees/count
• combination (page & nationality filter): http://localhost:3000/employees?_page=2&nationality=DE

---

getGeo

promise-based

fetch('http://localhost:3000/geo')
  .then(res => res.json())
  .then(console.log)

async/await-based

async function getGeo(){
  const res = await fetch('http://localhost:3000/geo')
  const geo = await res.json()
  return geo
}

getGeo().then(console.log)

---

fetching collection total size with X-Total-Count:

fetch('http://localhost:3000/benefits?country=Germany')
  .then(res => res.headers.get('X-Total-Count'))
  .then(console.log)

benefit.d.ts

import { Email } from './shared.d';

export type Benefit = {
  "id": string;
  "beneficiary": {
    name: string;
    email: Email;
  };
  "country": string;
  "city": string;
  "service": string;
  "monthlyFee": number;
  "subscribedAtDate": string;
};

def.d.ts

import { Nationality, BenefitServiceType } from './shared'

export type Department = {
  id: number;
  name: string;
}

export type CompanyDef = {
  name: string;
  departments: Department[]
}

type CountryDef = {
  name: string;
  contracts: {
    contract: number;
    permanent: number;
  }
  cities: {
    [city: string]: number[];
  }
  flags: {
    contractorsHaveBenefits: boolean;
  }
};

export type CountryDefMap = {
  [countryCode in Nationality]: CountryDef;
}

export type CountryBenefitsMap = {
  [benefit in BenefitServiceType]: {
    availability: Nationality[];
    monthlyCost: number;
  }
}

employee.d.ts

import { Nationality, DateString, Money, Phone, Email } from './shared';

export type Skill = string;

export type ContractType = "contract" | "permanent";

export type Employee = {
  "id": number;
  "nationality": Nationality,
  "departmentId": number;
  "keycardId": string;
  "account": string;
  "salary": Money;
  "office": [string, string];
  "firstName": string;
  "lastName": string;
  "title": string;
  "contractType": ContractType;
  "email": Email;
  "hiredAt": DateString;
  "expiresAt": DateString;
  "personalInfo": {
    "age": number;
    "phone": Phone;
    "email": Email;
    "dateOfBirth": DateString;
    "address": {
      "street": string;
      "city": string;
      "country": string;
    };
  },
  "skills": Skill[];
  "bio": string;
  "imgURL": string;
};

expense.d.ts

import { Money, DateString } from './shared';

export type Expense = {
  "id": string;
  "amount": Money;
  "title": string;
  "payerAccount": string;
  "beneficiaryAccount": string;
  "beneficiaryAddress": string;
  "scheduledAt": DateString;
};

index.d.ts

export * from './def'
export * from './shared'

export * from './benefit'
export * from './employee'
export * from './expense'
export * from './office'
export * from './project'

office.d.ts

import { Phone } from './shared';

export type Office = {
  "country": string;
  "city": string;
  "address": string;
  "estate": {
    "owner": string;
    "phone": Phone;
    "monthlyRental": number;
  };
  "imgURL": string;
};

project.d.ts

import { Money } from './shared';

export type Project = {
  "id": string;
  "name": string;
  "budget": Money;
  "startDate": string;
  "endDate": string;
  "team": {
    "id": number;
    "name": string;
  }[];
  "manager": number;
  "description": string;
};

shared.d.ts

export type Nationality = "US" | "UK" | "FR" | "DE" | "NL" | "PL" | "IT" | "ES";

export type BenefitServiceType = "lunch-card" | "healthcare" | "sport-system" | "cafeteria.io";

export type DateString = string;
export type Email = string;
export type Phone = string;
export type Money = number;