Api 응답 양식 결정 - 게임 웹서버 만들기 3

콘텐츠를 본격적으로 개발하기 전에,

먼저 API 응답 형식을 결정해두면

나중에 유지보수나 확장에 훨씬 유리합니다.

 

이번 글에서는 API 응답 양식을 정리해보겠습니다.

---

[Api 응답 양식]

Api 응답 양식을 미리 정의해두면,

클라이언트측에서 데이터를 처리하거나 디버깅할 때 일관된 구조의 데이터를 다룰 수 있어 편리합니다.

또한 모든 API가 같은 구조로 응답하기 때문에, 협업이나 에러 처리도 쉬워집니다.

 

---

 

ApiResponse 클래스는 전체 프로젝트에서 공통으로 사용될 예정이므로,

Common이라는 전용 폴더를 만들어 이 안에 관리하도록 하겠습니다.

 

 

 

추가->새 폴더로 Common 폴더를 생성해줍니다.

 

 

추가 -> 클래스로 'ApiResponse.cs'클래스를 생성해줍니다.

---

 

패킷의 기본 응답 구조는 위와 같이 정의합니다.

 

 

●ResultStatus

 : 현 Api 응답의 상태를 나타냅니다.

현재 기본값 : "Success", "Error"

 

필요시 다양한 상태를 추가하여 사용합니다.

 

● Data

실제 응답 데이터 Body를 담는 영역입니다.

 

● ErrorCode / ErrorMessage

 

---

 

 

Success의 경우와 Error의 경우를 각각 메서드로 만들어줍니다.

 

---

 

 

이제 기존에 기본 템플릿으로 생성된  WeatherForecast Api에서 테스트 해보도록 하겠습니다.

 

 

return ApiResponse<T>.Success(result);

 

위의 방식으로 응답을 변경합니다.

 

 

응답 양식이 변경된 것을 확인할 수 있습니다.

 

 

---

이하 코드 전문

 

-.Common/ApiResponse.cs

namespace PPProject.Common
{
    public class ApiResponse<T>
    {
        public enum ResultStatus
        {
            Success = 0,
            Error   = 1001
        }

        public ResultStatus Status { get; private set; }
        public T? Data { get; private set; }
        public int ErrorCode { get; private set; }
        public string? ErrorMessage { get; private set; }
        public static ApiResponse<T> Success(T data)
        {
            return new ApiResponse<T>
            {
                Status = ResultStatus.Success,
                Data = data,
                ErrorCode = 0,
                ErrorMessage = null
            };
        }

        public static ApiResponse<T> Error(int ErrorCode, string errorMessage)
        {
            return new ApiResponse<T>
            {
                Status = ResultStatus.Error,
                Data = default,
                ErrorCode = ErrorCode,
                ErrorMessage = errorMessage
            };
        }
    }
}

 

 

-. WeatherForecastController.cs

 

using Microsoft.AspNetCore.Mvc;
using PPProject.Common;

namespace PPProject.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries =
        [
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        ];

        [HttpGet(Name = "GetWeatherForecast")]
        public ApiResponse<IEnumerable<WeatherForecast>> Get()
        {
            var result = Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
            return ApiResponse<IEnumerable<WeatherForecast>>.Success(result);
        }
    }
}