{"id":21874166,"url":"https://github.com/eeue56/enum-api-design-examples","last_synced_at":"2025-03-21T23:17:51.015Z","repository":{"id":233337400,"uuid":"786932589","full_name":"eeue56/enum-api-design-examples","owner":"eeue56","description":"Examples of API designs when using enums","archived":false,"fork":false,"pushed_at":"2024-04-15T20:47:16.000Z","size":30,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-26T17:37:37.222Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eeue56.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-04-15T15:19:27.000Z","updated_at":"2024-04-15T18:52:14.000Z","dependencies_parsed_at":"2024-04-15T21:50:30.027Z","dependency_job_id":null,"html_url":"https://github.com/eeue56/enum-api-design-examples","commit_stats":null,"previous_names":["eeue56/enum-api-design-examples"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eeue56%2Fenum-api-design-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eeue56%2Fenum-api-design-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eeue56%2Fenum-api-design-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eeue56%2Fenum-api-design-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eeue56","download_url":"https://codeload.github.com/eeue56/enum-api-design-examples/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244880660,"owners_count":20525515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-28T07:11:19.058Z","updated_at":"2025-03-21T23:17:50.996Z","avatar_url":"https://github.com/eeue56.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# enum-api-design-examples\nExamples of API designs when using enums\n\n## The API\n\nWe're designing an API for animals, and would like to guide the user on what animals we consider valid.\n\nCurrently, we support:\n- Dog\n- Cat\n\nAn animal is an object with a species property, represented in pseudo-code as so:\n\n```typescript\ntype Animal = {\n    species: Cat | Dog\n}\n```\n\nHowever, there's a problem. While we'd like to guide the user on what species we know about, we will also allow for custom animals.\n\nIn pseudo-code, our animal support actually looks like:\n\n```typescript\ntype Animal = {\n    species: Cat | Dog | Custom\n}\n```\n\nKeeping the explicitly known species will help our users understand our API, but we need to be flexible.\n\nHow do we solve that in a reasonable way? To find out, we're going to branch from this commit and demostrate some example options.\n\n## Code\n\nTo begin with, we have an animal type and parser in [server/src/animal.ts](server/src/animal.ts) and [client/src/animal.ts](client/src/animal.ts), which both start out the same.\nIn the server, there's minimal logic, most of which lives in [server/src/index.ts](server/src/index.ts). It exposes a few endpoints:\n\n| Endpoint | Purpose |\n| -------- | ------- |\n| /reset   | Empty the \"database\" of all animals |\n| /list    | Get all the animals in the database, as an array |\n| /list/:species | Get all the animals of a particular species in the database, as an array |\n| POST /animal | If valid, add a new animal from the request body |\n\nIn the client, there's some logic that a client might typically do in [client/src/logic.ts](client/src/logic.ts). This includes:\n\n- Assigning a score to each animal, and providing the sum\n- Providing the count of each species\n- Filtering for a particular species, both the two known species (Cat, Dog), and unknown species\n\nThere's a test script in [client/src/index.ts](client/src/index.ts), which runs a series of commands against the API and prints the responses. Before making the test requests, it populates the database with some sample animals.\n\n## PRs\n\nTo get an overview of the choices, check out these PRs in order, and read the commits or the pull request body, along with the code, to see the impact each decision takes. In each PR, the test script has been run to examine the breaking changes made both client and server side.\n\n### Representing species as a string without restrictions\n\ne.g `type Species = string`\n\n- [Server code](https://github.com/eeue56/enum-api-design-examples/pull/1)\n- [Client code to ignore unknown species](https://github.com/eeue56/enum-api-design-examples/pull/2)\n- [Also set species to string on the client](https://github.com/eeue56/enum-api-design-examples/pull/3)\n\n### Representing species with a union of two disinct objects\n\ne.g `type Species = { kind: Known, value: string } | { kind: Custom | value: string }`\n\n- [Server code](https://github.com/eeue56/enum-api-design-examples/pull/4)\n- [Match server code on the client](https://github.com/eeue56/enum-api-design-examples/pull/5)\n\n## Usage\n\nTo run the server and see how data is parsed and handled, do the following:\n\n```\nnpm install\nnpm run start-server\n\nnpm run start-client\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feeue56%2Fenum-api-design-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feeue56%2Fenum-api-design-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feeue56%2Fenum-api-design-examples/lists"}