ASP.NET Web API의 라우팅

이 문서에서는 ASP.NET Web API HTTP 요청을 컨트롤러로 라우팅하는 방법을 설명합니다.

참고

ASP.NET MVC에 익숙한 경우 Web API 라우팅은 MVC 라우팅과 매우 유사합니다. 기본 차이점은 Web API가 URI 경로가 아닌 HTTP 동사를 사용하여 작업을 선택한다는 것입니다. Web API에서 MVC 스타일 라우팅을 사용할 수도 있습니다. 이 문서에서는 ASP.NET MVC에 대한 어떠한 지식도 가정하지 않습니다.

라우팅 테이블

ASP.NET Web API 컨트롤러는 HTTP 요청을 처리하는 클래스입니다. 컨트롤러의 공용 메서드를 작업 메서드 또는 단순히 작업이라고 합니다. Web API 프레임워크는 요청을 받으면 요청을 작업으로 라우팅합니다.

호출할 작업을 결정하기 위해 프레임워크는 라우팅 테이블을 사용합니다. Web API용 Visual Studio 프로젝트 템플릿은 기본 경로를 만듭니다.

routes.MapHttpRoute(
    name: "API Default",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

이 경로는 App_Start 디렉터리에 배치되는 WebApiConfig.cs 파일에 정의됩니다.

클래스에 WebApiConfig 대한 자세한 내용은 ASP.NET Web API 구성을 참조하세요.

Web API를 자체 호스팅하는 경우 개체에서 HttpSelfHostConfiguration 직접 라우팅 테이블을 설정해야 합니다. 자세한 내용은 웹 API 자체 호스팅을 참조하세요.

라우팅 테이블의 각 항목에는 경로 템플릿이 포함됩니다. Web API의 기본 경로 템플릿은 "api/{controller}/{id}"입니다. 이 템플릿에서 "api"는 리터럴 경로 세그먼트이며 {controller} 및 {id}는 자리 표시자 변수입니다.

Web API 프레임워크는 HTTP 요청을 받으면 라우팅 테이블의 경로 템플릿 중 하나에 대해 URI를 일치시키려고 시도합니다. 일치하는 경로가 없으면 클라이언트는 404 오류를 수신합니다. 예를 들어 다음 URI는 기본 경로와 일치합니다.

• /api/contacts
• /api/contacts/1
• /api/products/gizmo1

그러나 다음 URI는 "api" 세그먼트가 없기 때문에 일치하지 않습니다.

• /contacts/1

참고

경로에서 "api"를 사용하는 이유는 ASP.NET MVC 라우팅과의 충돌을 방지하기 위한 것입니다. 이렇게 하면 "/contacts"가 MVC 컨트롤러로 이동하고 "/api/contacts"가 Web API 컨트롤러로 이동하도록 할 수 있습니다. 물론 이 규칙이 마음에 들지 않으면 기본 경로 테이블을 변경할 수 있습니다.

일치하는 경로가 발견되면 Web API는 컨트롤러와 작업을 선택합니다.

• 컨트롤러를 찾기 위해 Web API는 {controller} 변수 값에 "Controller" 를 추가합니다.
• 작업을 찾기 위해 Web API는 HTTP 동사를 찾은 다음 이름이 해당 HTTP 동사 이름으로 시작하는 작업을 찾습니다. 예를 들어 GET 요청을 사용하면 Web API는 "GetContact" 또는 "GetAllContacts"와 같은 "Get"이라는 접두사로 된 작업을 찾습니다. 이 규칙은 GET, POST, PUT, DELETE, HEAD, OPTIONS 및 PATCH 동사에만 적용됩니다. 컨트롤러의 특성을 사용하여 다른 HTTP 동사를 사용하도록 설정할 수 있습니다. 그 예제는 나중에 확인할 수 있습니다.
• 경로 템플릿의 다른 자리 표시자 변수(예: {id}) 는 작업 매개 변수에 매핑됩니다.

예를 살펴보겠습니다. 다음 컨트롤러를 정의한다고 가정해 보겠습니다.

public class ProductsController : ApiController
{
    public IEnumerable<Product> GetAllProducts() { }
    public Product GetProductById(int id) { }
    public HttpResponseMessage DeleteProduct(int id){ }
}

다음은 각각에 대해 호출되는 작업과 함께 가능한 몇 가지 HTTP 요청입니다.

HTTP 동사	URI 경로	작업	매개 변수
GET	api/products	GetAllProducts	(없음)
GET	api/products/4	GetProductById	4
DELETE	api/products/4	DeleteProduct	4
POST	api/products	(일치하지 않음)

URI의 {id} 세그먼트가 있는 경우 작업의 id 매개 변수에 매핑됩니다. 이 예제에서 컨트롤러는 ID 매개 변수와 매개 변수가 없는 두 개의 GET 메서드를 정의합니다.

또한 컨트롤러가 "Post..." 메서드를 정의하지 않으므로 POST 요청이 실패합니다.

라우팅 변형

이전 섹션에서는 ASP.NET Web API 대한 기본 라우팅 메커니즘을 설명했습니다. 이 섹션에서는 몇 가지 변형에 대해 설명합니다.

HTTP 동사

HTTP 동사에 대한 명명 규칙을 사용하는 대신 다음 특성 중 하나로 작업 메서드를 데코레이팅하여 작업의 HTTP 동사를 명시적으로 지정할 수 있습니다.

• [HttpGet]
• [HttpPut]
• [HttpPost]
• [HttpDelete]
• [HttpHead]
• [HttpOptions]
• [HttpPatch]

다음 예제에서는 메서드가 FindProduct GET 요청에 매핑됩니다.

public class ProductsController : ApiController
{
    [HttpGet]
    public Product FindProduct(id) {}
}

작업에 대해 여러 HTTP 동사를 허용하거나 GET, PUT, POST, DELETE, HEAD, OPTIONS 및 PATCH 이외의 HTTP 동사를 허용하려면 HTTP 동사 목록을 사용하는 특성을 사용합니다[AcceptVerbs].

public class ProductsController : ApiController
{
    [AcceptVerbs("GET", "HEAD")]
    public Product FindProduct(id) { }

    // WebDAV method
    [AcceptVerbs("MKCOL")]
    public void MakeCollection() { }
}

작업 이름으로 라우팅

기본 라우팅 템플릿을 사용하여 Web API는 HTTP 동사를 사용하여 작업을 선택합니다. 그러나 작업 이름이 URI에 포함된 경로를 만들 수도 있습니다.

routes.MapHttpRoute(
    name: "ActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

이 경로 템플릿에서 {action} 매개 변수는 컨트롤러의 작업 메서드 이름을 지정합니다. 이 라우팅 스타일을 사용하면 특성을 사용하여 허용되는 HTTP 동사를 지정합니다. 예를 들어 컨트롤러에 다음 메서드가 있다고 가정합니다.

public class ProductsController : ApiController
{
    [HttpGet]
    public string Details(int id);
}

이 경우 "api/products/details/1"에 대한 GET 요청이 메서드에 Details 매핑됩니다. 이 라우팅 스타일은 ASP.NET MVC와 유사하며 RPC 스타일 API에 적합할 수 있습니다.

특성을 사용하여 작업 이름을 재정의할 [ActionName] 수 있습니다. 다음 예제에는 "api/products/thumbnail/id"에 매핑되는 두 가지 작업이 있습니다. 하나는 GET을 지원하고 다른 하나는 POST를 지원합니다.

public class ProductsController : ApiController
{
    [HttpGet]
    [ActionName("Thumbnail")]
    public HttpResponseMessage GetThumbnailImage(int id);

    [HttpPost]
    [ActionName("Thumbnail")]
    public void AddThumbnailImage(int id);
}

비 동작

메서드가 작업으로 호출되지 않도록 하려면 특성을 사용합니다 [NonAction] . 이는 메서드가 라우팅 규칙과 일치하지 않더라도 동작이 아니라는 신호를 프레임워크에 보냅니다.

// Not an action method.
[NonAction]  
public string GetPrivateData() { ... }

추가 정보

이 항목에서는 라우팅에 대한 개략적인 보기를 제공했습니다. 자세한 내용은 라우팅 및 작업 선택을 참조하세요. 이 선택에서는 프레임워크가 경로에 URI를 일치시키고 컨트롤러를 선택한 다음 호출할 작업을 선택하는 방법을 정확하게 설명합니다.