Animal Shelter API

By Will W.

Build an API using C#/.NET

💻 Technologies Used

• C#
• .NET 5.0
• Linq
• Swagger
• ASP.NET Core
• Razor
• Entity Framework Core
• MySQL
• dotnet script REPL

📝 Description

The objective of this project was to create an API with full CRUD capabilities using C#/.NET WebApi. Along with the API we were tasked with further exploration in any number of topics in order to give us a chance to push ourselves. You will find the API & my further explorations listed below.

Pagination

Currently we return paginated values our API. By default we set a max page size of 10.

pageSize={int}

Sets page size for returned values, only applicable to `/api/Animals` as it returns a list.

Defaults to 10, with a maximum value of 10.

pageNumber={int}

Returns the values located in that page.

EX: 100 total animals, a pageNumber of 2 will return the animals located in rows 11 to 20.

Defaults to 1.

Versioning

This API implements versioning in order to provide backwards compatibility as changes are made to extend functionality.

Endpoints

Our API implements two versions. All functionality from V1.0 is present in V2.0 unless noted otherwise. The URLs for each version of the API are versioned as well, but if you choose to not use a version string in them it will default to using v2.0.

/api/v1.0/Animals   # Version 1.0
/api/v2.0/Animals   # Version 2.0
/api/Animals        # Version 2.0

V1.0

/api/v1.0/Animals

GET /api/v1.0/Animals

Returns an unfiltered, paginated list of animals.

Takes no parameters besides those used for pagination (pageNumber and pageSize).

Parameters

• pageNumber: The page you would like to visit.
• pageSize: The size of each page.

POST /api/v1.0/Animals

Adds an animal to the database. The following values should be provided to create the animal:

• Name: Required, Max of 40 characters.
• Breed: Required, Max of 40 characters.
• Species: Required, Max of 40 characters.
• Description: Required.
• Status: Required, one of ["Available", "Adopted"], may also be 0 or 1.

EX:

{
  "Name": "This is a name",
  "Breed": "This is a breed",
  "Species": "This is a species",
  "Description": "This is a description",
  "Status": 1
}

An AnimalId is not required to add an animal to the database as an ID will be generated for it.

/api/v1.0/Animals/{id}

GET /api/v1.0/Animals/{id}

Returns a listing for an animal with an ID of {id}.

Example return body of an Animal where {id} is 6:

{
  "AnimalId": 6,
  "Name": "Maximum Red Purple",
  "Breed": "Jungle Green",
  "Species": "Maximum Yellow Red",
  "Description": "Mulberry Sky Blue Madder ...",
  "Status": 1
}

PUT /api/v1.0/Animals/{id}

Modify an animal with an ID of {id}.

The body of the Animal object must contain an `AnimalId` field with a value matching {id}. Other than the AnimalId you only have to include the fields that you are updating.

Example body content where {id} is equal to 6

{
  "AnimalId": 6,
  "Name": "New Name",
  "Breed": "New Description",
  "Species": "Bar",
  "Description": "Foo",
  "Status": 0
}

DELETE /api/v1.0/Animals/{id}

Permanently deletes an animal from the database if there is an Animal with an AnimalId equal to {id}.

V2.0

/api/v2.0/Animals

GET /api/v2.0/Animals

Returns a filtered, paginated list of animals.

No parameters are required, but available parameters are listed below.

Parameters

• pageNumber: The page you would like to visit.
• pageSize: The size of each page.
• name: The exact name of the animal you would like to find listed.
• breed: The exact breed of the animal you would like to find listed.
• species: The exact species of the animal you would like to find listed.
• description: A substring you would like to find contained in the description of an animal.
• status: Required, one of ["Available", "Adopted"], may also be 0 or 1.

/api/v2.0/Animals/Random

GET /api/v2.0/Animals

Returns a single random animal from the database.

Swagger

This project uses Swashbuckle to generate Swagger documentation for the API. After building and running the API you can view that documentation by visiting http://localhost:5000/swagger.

Please note that there are two versions of the API available, and to view the documentation for v2.0 please select it from the drop down list in the top right corner.

⚙️ Setup/Installation & Usage Instructions

• Install the MySQL Community Server & MySQL Workbench
• Install the .NET 5 SDK
• Install the dotnet-ef tool with this command: dotnet tool install --global dotnet-ef
• Clone this repository to your device
• Create appsettings.json in the top level of this repo
  • Copy the contents of the code below into this file. Make sure to change the password to the password you used to setup your MySQL server

  {
    "ConnectionStrings": {
        "DefaultConnection": "Server=localhost;Port=3306;database=will_watkins;uid=root;pwd=<PASSWORD>;"
    }
  }

• Using your terminal navigate to the directory where you have cloned this repo.
• Run dotnet build AnimalShelter.Api in the top level directory of this repo.
• Once the project has been built run dotnet ef database update --project AnimalShelter.Api to create the database necessary to run the app.
• Run dotnet run --project AnimalShelter.Api to get the program running, and the site hosted locally.
• Open your browser and visit http://localhost:5000/ and it will redirect you to the Swagger documentation.
• Access the API endpoints directly by using Postman or by using cURL.

📄 Notes

• There is quite a bit of sprawl here that should be refactored. Specifically Startup.cs can be a bit hard to follow.

🐞 Known Bugs

• If any are found please feel free to open an issue or email me at wjwat at onionslice dot org

⚠️ License

MIT License

Copyright (c) 2022 Will W. ╮(￣ω￣;)╭