PokeAPI SDK — @georgedoescode

Hey, Speakeasy team! I hope you are all doing well.

I appreciate you all taking the time to review my submission. To be candid, developing SDKs is a little out of my wheelhouse as a developer who sits in design engineering space — but I really enjoyed this task. It's a really interesting space to work in and I'd love to do some more exploration.

High level Process

• I kicked things off my studying the pokeapi docs. I sent a few test requests, and familiarized myself with the API.
• Next, I checked out a few SDKs that I knew folks enjoyed using. This is a space that is quite new to me, so I wanted to get inspiration for best practices/design patterns.
• Once I had an idea of the direction I wanted to go in, I created my development environment and began writing code.
• As I worked through the task, I made notes on design decisions, potential improvements, and setup intructions for (this) readme.
• Once I had the structure of the SDK layed out, I wrote some simple tests that would allow me to verify my work locally.
• From here, it was a process of iteration until near the end of my development timebox.

Design decisions

My overall approach for this task was to keep it simple, and add small DX improvements where I could. I am aware of my limitations, and did not want to reinvent the wheel. I figured a simple SDK with good documentation/tests would be preferred.

Tech stack

I opted for vite/vitest as I have worked with them in the past to develop publicly available libraries. I knew that this route would save me time on setting up boilerplate code, and that it would be easy enough to ensure the package could be published with functioning types/imports.

I chose TypeScript for my language.

Structure

After studying some existing SDK implementations, I found that creating a "base" SDK class and extending it for different resources was an established pattern, so I tried to follow this approach. I also found that the majority of SDK implementations I studied used an OOP/Class based approach, so I stuck with that convention too.

I opted for a fairly flat structure as the scope for the task was quite narrow:

src/ 
  lib/ 
    sdk-base.ts
  sdk/
    generations.ts
    pokemon.ts
    types.ts

If this was a larger project, I may look to separate things out a little more. Perhaps something like:

src/ 
  lib/ 
    sdk-base.ts
  sdk/
    generations/ 
      generations.ts
      types.ts
    ...

Installation

• git clone
• npm install

Testing

• npm run test for local development.
• npm coverage for test coverage.

Usage

Potential improvements

• I decided to focus on building out the SDK and documentation rather than defining types. Beacause of this, my type definintions are quite sparse!
• I could have implemented zod or something similar to verify that the API responses matched the shapes I expected. With my current setup, I am putting trust in the API.
• There is some duplication around how I handle pagination. I'd like to try and abstract this out.
• I could create a mock for the API to use for my tests.
• I could have added caching, although that would be a larger lift to handle well.
• I have very closesly related PaginatedAPIResponse and PaginatedSDKResponse types.
• Error handling withing my sdk-base could be more robust.
• I ran out of time to add all the tests I wanted to, so my coverage is not fantastic.