Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
228 lines (176 loc) · 4.79 KB

DOCUMENTATION.md

File metadata and controls

228 lines (176 loc) · 4.79 KB

PERSON REST API

The PERSON REST API is a simple API that allows you to perform CRUD operations on the "Person" resource. It provides endpoints for creating, retrieving, updating, and deleting persons. This document provides an overview of the API, how to use it, and how to set it up for local development or deployment.

Table of Contents

Endpoints

The API offers the following endpoints:

Create a New Person

{
  "name": "John",
  "email": "john@gmail.com"
}
  • Response Format:
{
  "id": 1,
  "name": "John",
  "email": "john@gmail.com"
}

Get All Persons

{
  "name": "John",
  "email": "john@gmail.com"
}
  • Response Format:
{
  "id": 1,
  "name": "John",
  "email": "john@gmail.com"
}

Get Person by ID -Endpoint: GET https://person-crud-api-bdzs.onrender.com/api/{id} -Description: Retrieve details of a person by their ID. -Response Format

{
  "id": 1,
  "name": "John",
  "email": "john@gmail.com"
}

Update Person -Endpoint: PUT https://person-crud-api-bdzs.onrender.com/api/{id} -Description: Update details of an existing person. -Request Format:

{
  "first_name": "John"
}

Response Format

{
  "id": 1,
  "name": "John",
  "email": ""
}

Delete Person Endpoint: DELETE https://person-crud-api-bdzs.onrender.com/api/{id} Description:** Remove a person by their ID. Response Format:

{
  "message": "Person has been deleted."
}

Standard Formats

Request Format: All request data should be provided in JSON format in the request body. Response Format: All responses are in JSON format.

Usage You can use the PERSON REST API to manage persons in your application. Below are some sample usages:

Create a New Person:

Request POST https://person-crud-api-bdzs.onrender.com/api Content-Type: application/json

{
  "name": "John",
  "email": "john@gmail"
}

Response

{
  "name": "John",
  "email": "john@gmail"
}

Get All Persons: Request GET https://person-crud-api-bdzs.onrender.com/api

Response

{
  "name": "John",
  "email": "john@gmail"
}

Get Person by ID: Request GET https://person-crud-api-bdzs.onrender.com/api/{id}

Response

{
  "name": "John",
  "email": "john@gmail"
}

Update Person: PUT https://person-crud-api-bdzs.onrender.com/api/{id} Content-Type: application/json

{
  "first_name": "Jane"
}

Response

{
  "id": 1,
  "name": "Jane",
  "email": ""
}

Delete Person: Request DELETE https://person-crud-api-bdzs.onrender.com/api/{id} Response

{
  "message": "Person has been deleted."
}

Known Limitations

  1. Only string data types are allowed for name and email fields.
  2. The API does not support pagination for listing persons.
  3. No authentication and authorization mechanisms are implemented in this version.

Setup

Follow these steps to set up and run the API locally:

Clone the repository: git clone https://github.com/Mac-5/PersonApi.git

Install dependencies:

cd your-api go mod tidy

Configure the database: Update the database configuration in your application code if needed. Ensure that the database server is running.

Run the API:

go run main.go

The API will be accessible at http://localhost:PORT, where PORT is the port specified in your configuration.

Testing:

Test the API using tools like Postman or curl. Refer to the "Sample Usage" section for examples.

Deployment:

To deploy the API on a server, follow your server hosting provider's deployment instructions. Ensure that the server environment is properly configured and that your API is accessible over the internet.