ASP.NET Core로 첫 Web API 구축하기 파트 1: REST 시작하기

Source: Dev.to

위 링크에 있는 전체 텍스트를 제공해 주시면, 해당 내용을 한국어로 번역해 드리겠습니다. 코드 블록, URL 및 기술 용어는 그대로 유지하고, 나머지 내용만 번역해 드립니다.

REST란 무엇인가?

REST(Representational State Transfer)는 네트워크 서비스 설계를 위한 아키텍처 패턴입니다. 브라우저가 매일 사용하는 표준 HTTP 동사를 사용하여 리소스에 대한 작업을 수행합니다.

RESTful API는 다음 세 가지 요소로 정의됩니다:

1. 기본 URI (예: https://api.example.com)
2. 위의 HTTP 메서드
3. 데이터 형식—보통 JSON, 경우에 따라 XML

라우팅은 모든 것을 연결합니다. 예를 들어, /pizza에 대한 요청은 PizzaController로, /order에 대한 요청은 OrderController로 라우팅될 수 있습니다. 각 리소스는 코드 내에서 자신의 논리적 위치를 갖게 됩니다.

왜 ASP.NET Core인가?

• 즉시 사용 가능한 JSON – ASP.NET Core는 C# 클래스를 자동으로 JSON으로 직렬화합니다.
• 내장 보안 – HTTPS가 기본적으로 활성화되어 있으며, JWT 인증 및 정책 기반 권한 부여를 기본 지원합니다.
• 속성 기반 라우팅 – 속성을 사용해 컨트롤러 메서드에 직접 라우트를 정의함으로써 라우팅 로직을 코드와 함께 위치시킵니다.
• .NET 전반에 걸친 코드 재사용 – 동일한 모델과 비즈니스 로직을 모바일, 데스크톱, 기타 .NET 서비스와 공유할 수 있습니다.

Prerequisites

• C#에 대한 기본적인 친숙함(초급 수준이면 충분합니다)
• 로컬에 .NET 8 SDK가 설치되어 있음
• Visual Studio Code
• VS Code용 C# Dev Kit 확장 프로그램
• VS Code용 REST Client 확장 프로그램

.NET 버전을 확인하려면 다음 명령을 실행하세요:

dotnet --list-sdks

8.0.100과 같은 결과가 표시되어야 합니다. 그렇지 않다면 공식 Microsoft 사이트에서 최신 .NET 8 SDK를 다운로드하세요.

프로젝트 만들기

1. VS Code → File > Open Folder 를 열고 ContosoPizza 라는 새 폴더를 만듭니다.
2. 통합 터미널을 엽니다 (View > Terminal) 그리고 다음을 실행합니다:

dotnet new webapi -controllers -f net8.0

이 명령은 컨트롤러 지원이 포함된 새로운 ASP.NET Core Web API 프로젝트를 스캐폴딩합니다. 생성된 구조는 다음과 같습니다:

├── Controllers/
├── obj/
├── Properties/
├── appsettings.Development.json
├── appsettings.json
├── ContosoPizza.csproj
├── ContosoPizza.http
├── Program.cs
└── WeatherForecast.cs

핵심 항목

• Controllers/ – API 엔드포인트 로직이 위치하는 곳
• Program.cs – 앱 시작 구성 및 HTTP 파이프라인
• ContosoPizza.http – VS Code 내부에서 API를 테스트할 때 유용한 파일
• ContosoPizza.csproj – 프로젝트 메타데이터 및 종속성

VS Code에서 디버깅 자산을 추가하라는 메시지가 표시될 수 있습니다—Yes 를 클릭하세요.

API 실행

개발 서버를 시작합니다:

dotnet run

다음과 같은 출력이 표시됩니다:

Now listening on: https://localhost:7294
Now listening on: http://localhost:5118
Application started. Press Ctrl+C to shut down.

HTTPS 포트(예: 7294)를 확인하세요. 브라우저를 열고 다음으로 이동합니다:

https://localhost:{PORT}/weatherforecast

무작위 날씨 데이터가 포함된 JSON 응답을 받아야 하며, 이는 스캐폴드된 엔드포인트가 정상 작동함을 확인시켜 줍니다.

REST Client 확장 프로그램으로 테스트하기

프로젝트에는 REST Client 확장 프로그램과 함께 사용할 수 있는 ContosoPizza.http 파일이 포함되어 있습니다. 파일을 열면 이미 /weatherforecast에 대한 GET 요청이 들어 있습니다.

Send Request 버튼을 GET 라인 위에서 클릭합니다. 응답 패널에 다음과 같은 내용이 표시됩니다:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...

[
  {
    "date": "2024-01-18",
    "temperatureC": -2,
    "temperatureF": 29,
    "summary": "Warm"
  },
  ...
]

이 워크플로우를 사용하면 VS Code를 떠나지 않고도 엔드포인트를 테스트할 수 있습니다.

HTTP REPL로 테스트하기

ASP.NET Core는 HTTP REPL이라는 대화형 도구도 제공합니다.

전역으로 설치합니다:

dotnet tool install -g Microsoft.dotnet-httprepl

실행 중인 API에 연결합니다:

httprepl https://localhost:{PORT}

REPL 안에서 파일 시스템처럼 API를 탐색할 수 있습니다:

ls                    # 사용 가능한 엔드포인트 목록
cd WeatherForecast    # 엔드포인트로 이동
get                   # GET 요청 실행
exit                  # REPL 종료

다음은?

현재 프로젝트에는 샘플 weather‑forecast 엔드포인트만 포함되어 있습니다. 파트 2에서는 다음을 진행합니다:

• ASP.NET Core 컨트롤러가 어떻게 동작하는지 살펴보기
• WeatherForecastController 코드를 상세히 분석하기
• Pizza 모델과 인‑메모리 데이터 서비스를 만들기
• 커스텀 PizzaController를 연결하기

파트 2를 마치면 자체 API 엔드포인트를 통해 피자 데이터를 가져올 수 있게 됩니다.

---

Tags: dotnet csharp webapi aspnetcore beginners