TAEYO.NET

Web API 프로젝트 만들기

이번 자습서에서는 ASP.NET Web API를 사용하여 제품 목록을 반환하는 Web API를 만들어 볼 텐데, 프론트 엔드 웹 페이지에서는 jQuery를 사용하여 결과를 출력할 예정이다.

Visual Studio를 시작하고 [시작 페이지]에서 [새 프로젝트]를 선택하거나 [파일] 메뉴에서 [새로 만들기][프로젝트]를 선택하자.

그 다음, [템플릿] 영역에서 [Visual C#]을 확장하고 [Web]을 선택하자. 프로젝트 템플릿 목록에서 [ASP.NET 웹 응용프로그램]을 선택하고 프로젝트 이름으로 “ProductsApp”을 입력한 다음 [확인]을 선택하자.

[새 ASP.NET 프로젝트] 대화상자에서 [Empty]을 선택하고 [다음의 폴더 및 코어 참조 추가] 영역에서 [Web API]를 선택하고 [확인]을 클릭하자.

[Web API] 템플릿을 사용하여 Web API 프로젝트를 만들 수도 있다. Web API 템플릿은 API 도우미 페이지를 제공하기 위해서 ASP.NET MVC를 사용한다. 이번 자습서에서는 빈 템플릿을 사용하고 있는데 그 이유는 MVC와 무관하게 Web API만을 보여주고자 하기 때문이다. 일반적으로 Web API를 사용하기 위해서 ASP.NET MVC까지 알아야 할 필요는 없다.

모델 추가하기

model은 응용프로그램 안에서 데이터를 표현하는 개체이다. ASP.NET Web API는 여러분의 모델을 자동으로 JSON, XML 혹은 그 밖의 다른 포맷으로 직렬화할 수 있으며, 직렬화된 데이터를 HTTP 응답 메시지의 본문에 작성할 수 있다. 클라이어트가 직렬화 포맷을 읽을 수 있다면 그는 개체를 역질렬화할 수 있을 것이다. 대부분의 클라이언트는 XML이나 JSON을 파싱할 수 있다. 뿐만 아니라, 클라이언트는 HTTP 요청 메시지 안에 Accept 헤더를 설정하여 자신이 원하는 데이터 포맷이 무엇인지를 알릴 수도 있다.

이제 제품(product)을 나타내는 간단한 모델을 하나 만들어 보도록 하자.

만일, 솔루션 탐색기가 아직 보이지 않는다면 [보기] 메뉴에서 [솔루션 탐색기]를 선택하도록 하자. 솔루션 탐색기에서 Models 폴더를 마우스 우클릭하고, 컨텍스트 메뉴에서 [추가]와 [클래스]를 이어서 선택해보자.

클래스의 이름으로는 “Product”를 주고 Product 클래스에 다음과 같이 속성들을 추가하자.

namespace ProductsApp.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Category { get; set; }
        public decimal Price { get; set; }
    }
}

컨트롤러 추가하기

Web API에서 컨트롤러는 HTTP 요청을 처리하는 개체이다. 필자는 제품의 전체 목록을 반환하거나 또는 특정 ID에 해당하는 단일 제품을 반환하는 컨트롤러를 추가해 볼까 한다

Note 만일 ASP.NET MVC를 사용해본 경험이 있다면 컨트롤러에 대해서는 이미 익숙할 것이다. Web API 컨트롤러는 MVC 컨트롤러와 유사하지만 Controller 클래스가 아닌 ApiController 클래스로부터 상속을 받는다는 점이 다르다.

[솔루션 탐색기]에서 Controllers 폴더에 마우스 우클릭을 하고 [추가][컨트롤러]를 선택하자.

[스캐폴드 추가하기] 대화상자가 나타나면 [Web API Controller ? Empty]를 선택하고 [추가]를 클릭한다

[컨트롤러 추가하기] 대화상자에서는 컨트롤러의 이름으로 “ProductsController”를 입력하고 [추가]를 클릭하자.

그러면, 스캐폴딩은 ProductsController.cs라는 파일을 Controllers 폴더 안에 생성할 것이다.

모든 컨트롤러들을 Controllers라는 폴더에 두어야 하는 것은 아니다. 그 폴더는 단지 소스 파일들을 깔끔하게 정리할 수 있도록 하기 위해서 준비된 것이니 말이다.

아직 파일이 열려져 있지 않다면 파일을 더블클릭해서 열도록 한다. 그리고 다음과 같이 파일에 코드를 작성하도록 하자.

using ProductsApp.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Web.Http;
namespace ProductsApp.Controllers
{
    public class ProductsController : ApiController
    {
        Product[] products = new Product[] 
        { 
            new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 }, 
            new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M }, 
            new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M } 
        };
        public IEnumerable<Product> GetAllProducts()
        {
            return products;
        }
        public IHttpActionResult GetProduct(int id)
        {
            var product = products.FirstOrDefault((p) => p.Id == id);
            if (product == null)
            {
                return NotFound();
            }
            return Ok(product);
        }
    }
}

간단한 수준의 예제이기에, 제품들은 컨트롤러 클래스 안에서 고정 배열에 저장하고 있다. 물론, 실제 응용프로그램이라면 데이터베이스에 질의하거나 어떤 다른 외부 데이터 저장소를 사용할 것이지만 말이다.

컨트롤러는 제품들을 반환하는 2개의 메서드를 정의하고 있다.

GetAllProducts 메서드는 전체 제품목록을 IEnumerable 형식으로 반환한다.
GetProduct 메서드는 ID를 사용해서 단일 제품을 찾아준다

이것이 전부다. 이제 여러분은 실제로 동작하는 Web API를 만든 것이다. 각각의 메서드는 다음과 같이 하나 이상의 URL과 매핑된다.

컨트롤러 메서드	URI
GetAllProducts	/api/products
GetProduct	/api/products/id

GetProduct 메서드의 URI안에 있는 id는 일종의 위치지정자이다. 예를 들면, 5라는 ID를 갖는 제품을 얻어내기 위한 URI는 api/products/5라는 것이다.

Web API가 HTTP 요청을 컨트롤러 메서드로 라우트하는 방법에 대해서 더 자세히 알고 싶다면 Routing in ASP.NET Web API 컬럼을 참고하기 바란다.

Javascript와 jQuery로 Web API 호출하기

이번 절에서는 HTML 페이지를 추가하고 AJAX를 사용하여 Web API를 호출해 볼 것이다. AJAX 호출을 수행하고 그 결과로 페이지를 갱신하는 작업은 jQuery를 사용하여 할 것이다.

솔루션 탐색기에서 프로젝트에 마우스 우클릭을 하고 [추가] 및 [새 항목]을 선택하자.

[새 항목 추가하기] 대화상자에서 [Visual C#] 하위로 [Web] 영역을 선택하자. 그 다음 우측 패널에서 HTML 페이지를 선택하고 페이지 이름으로는 index.html을 주도록 하자.

그 다음, 파일의 내용을 다음과 같이 변경하도록 하자.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Product App</title>
</head>
<body>
  <div>
    <h2>All Products</h2>
    <ul id="products" />
  </div>
  <div>
    <h2>Search by ID</h2>
    <input type="text" id="prodId" size="5" />
    <input type="button" value="Search" onclick="find();" />
    <p id="product" />
  </div>
  <script src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.min.js"></script>
  <script>
    var uri = 'api/products';
    $(document).ready(function () {
      // Send an AJAX request
      $.getJSON(uri)
          .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
              // Add a list item for the product.
              $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
          });
    });
    function formatItem(item) {
      return item.Name + ': $' + item.Price;
    }
    function find() {
      var id = $('#prodId').val();
      $.getJSON(uri + '/' + id)
          .done(function (data) {
            $('#product').text(formatItem(data));
          })
          .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
          });
    }
  </script>
</body>
</html>

jQuery를 구하는 방법은 여러 가지가 있다. 이번 예제에서는 Microsoft Ajax CDN을 사용하고 있으나, 여러분은 http://jquery.com/에서 직접 다운로드 할 수도 있다. 더불어, ASP.NET Web API 프로젝트 템플릿을 사용하여 프로젝트를 만들면 jQuery가 자동으로 포함되기도 하다.

제품 목록 가져오기

제품 목록을 가져오려면 /api/products로 HTTP GET 요청을 보내면 된다.

jQuery의 getJSON 함수는 AJAX 요청을 전송한다. 응답으로는 JSON 개체 배열을 받을 것이다. done 함수에는 요청이 성공한 경우 호출되는 콜백을 지정할 수 있으며, 콜백 안에서는 DOM을 제품 정보로 갱신하고 있다.

$(document).ready(function () {
    // Send an AJAX request
    $.getJSON(apiUrl)
        .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
                // Add a list item for the product.
                $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
        });
});

ID를 사용하여 제품 가져오기

ID로 제품을 가져오려면 /api/products/id 로 HTTP GET 요청을 전송하면 된다. 단, 여기서 id인자의 값으로는 제품의 ID를 지정해야 한다.

function find() {
    var id = $('#prodId').val();
    $.getJSON(apiUrl + '/' + id)
        .done(function (data) {
            $('#product').text(formatItem(data));
        })
        .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
        });
}

AJAX 요청을 보내기 위해서 여전히 getJSON을 호출하고 있지만 여기서는 요청 URI에 ID를 더하고 있다. 이 요청의 응답은 단일 제품의 JSON 표현이 될 것이다.

응용프로그램 실행

F5를 눌러 응용프로그램의 디버깅을 시작하자. 웹 페이지가 다음과 같이 나타날 것이다.

ID로 제품을 가져오려면, ID를 입력하고 Search를 클릭하면 된다.

유효하지 않은 ID를 입력하면 서버는 HTTP 에러는 반환할 것이다.

HTTP 요청과 응답을 보기 위해서 F12 기능 사용하기

HTTP 서비스를 사용하는 경우, HTTP 요청과 요청 메시지를 살펴보는 것은 대단히 유용하다. 인터넷 익스플로러 9에서는 F12 개발자 도구라는 것을 사용하여 이러한 작업을 수행할 수 있다. 여러분이 IE 9 이상을 사용하고 있다면 F12를 눌러서 도구를 열어보도록 하자. 그런 다음, Network 탭을 선택하고 [캡춰 시작]을 클릭하자. 이제 웹 페이지로 돌아와서 F5 버튼을 눌러서 페이지를 새로 고쳐보자. IE는 브러우저와 웹 서버 사이의 HTTP 트래픽을 캡춰할 것이다. [요약 뷰]에서는 페이지의 모든 네트워크 트래픽을 살펴볼 수 있다.

api/products/라는 상대경로의 URI를 갖는 항목을 찾아 선택하고 [자세히 보기] 혹은 [Go to detailed view ]를 클릭하자. 상세보기 화면에서는 요청과 응답의 헤더 및 본문을 보여주는 탭들이 존재한다. 예를 들어, [요청 헤더] 탭을 클릭하면 클라이언트가 Accept 헤더로 “application/json”를 요청한 것을 확인할 수 있다.

응답 본문 탭을 선택한다면 제품 목록이 JSON으로 직렬화된 것을 볼 수 있을 것이다. 다른 브라우저도 이러한 비슷한 기능을 제공하고 있다. 더불어, 또 하나의 유용한 툴로는 웹 디버깅 프록시인 Fiddler도 있다. Fiddler를 사용하면 모든 HTTP 트래픽을 살펴볼 수 있을 뿐만 아니라 요청의 HTTP 헤더를 완전하게 제어할 수 있으므로 HTTP 요청들을 조작할 수도 있다.

이 컬럼은 번역 당시 2014년 12월 12일에 최종 업데이트 되었음