ASP.NET Core 및 Windows용 Visual Studio를 사용하여 Web API 만들기

작성자 admin 작성일자 25th 5월 201829th 5월 2018

개요

이 자습서에서는 다음 API를 만듭니다.

API	설명	요청 본문	응답 본문
GET /api/todo	할 일 항목 모두 가져오기	없음	할 일 항목의 배열
GET /api/todo/{id}	ID로 항목 가져오기	없음	할 일 항목
POST /api/todo	새 항목 추가	할 일 항목	할 일 항목
PUT /api/todo/{id}	기존 항목 업데이트	할 일 항목	없음
DELETE /api/todo/{id}	항목 삭제	없음	없음

다음 다이어그램에서는 앱의 기본 디자인을 보여 줍니다.

웹 API를 사용하는 어떤 것도 클라이언트에 해당합니다(모바일 앱, 브라우저 등). 이 자습서에서는 클라이언트를 만들지 않습니다. Postman 또는 curl은 앱을 테스트하기 위한 클라이언트로 사용됩니다.
모델은 앱에서 데이터를 나타내는 개체입니다. 이 경우 유일한 모델은 할 일 항목입니다. 모델은 C# 클래스로 표현되며 POCO(Plain Old C# Object)로도 알려져 있습니다.
컨트롤러는 HTTP 요청을 처리하고 HTTP 응답을 만드는 개체입니다. 이 앱에는 단일 컨트롤러가 있습니다.
자습서를 간단히 유지하기 위해 앱은 영구 데이터베이스를 사용하지 않습니다. 샘플 앱은 메모리 내 데이터베이스에 할 일 항목을 저장합니다.

전제 조건

Visual Studio for Windows

ASP.NET and web development workload
.NET Core cross-platform development workload
X.509 security certificate

프로젝트를 만듭니다.

Visual Studio에서 다음 단계를 수행합니다.

파일 메뉴에서 새로 만들기 > 프로젝트를 선택합니다.
ASP.NET Core 웹 응용 프로그램 템플릿을 선택합니다. 프로젝트 이름을 TodoApi로 지정하고 확인을 클릭합니다.

만일 ASP.NET Core를 선택할 수 없다면,ASP.NET Core를 추가 설치 하도록 한다.https://www.microsoft.com/net/learn/get-started/windows
https://www.microsoft.com/net/download/visual-studio-sdks
새 ASP.NET Core 웹 응용 프로그램 – TodoApi 대화 상자에서 ASP.NET Core 버전을 선택합니다. API 템플릿을 선택하고 확인을 클릭합니다.Docker 지원 사용을 선택하지 마세요.

상세 보기

앱 시작

Visual Studio에서 CTRL+F5를 눌러 앱을 시작합니다. Visual Studio가 브라우저를 시작하고 http://localhost:<port>/api/values로 이동합니다. 여기서 <port>는 임의로 선택된 포트 번호입니다. Chrome, Microsoft Edge 및 Firefox에는 다음 출력이 표시됩니다.

모델 클래스 추가

모델은 앱의 데이터를 나타내는 개체입니다. 이 경우 유일한 모델은 할 일 항목입니다.

솔루션 탐색기에서 프로젝트를 마우스 오른쪽 단추로 클릭합니다. 추가 > 새 폴더를 선택합니다. 폴더 이름을 Models로 지정합니다.

참고

모델 클래스는 프로젝트의 어디에서나 사용될 수 있습니다. Models 폴더는 모델 클래스에 대한 규칙에 사용됩니다.

솔루션 탐색기에서 Models 폴더를 마우스 오른쪽 단추로 클릭하고 추가 > 클래스를 선택합니다. 클래스 이름을 TodoItem으로 지정하고 추가를 클릭합니다.

TodoItem 클래스를 다음 코드로 업데이트합니다.

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

TodoItem이 만들어질 때 데이터베이스가 Id를 생성합니다.

데이터베이스 컨텍스트 만들기

데이터베이스 컨텍스트는 특정 데이터 모델에 맞게 Entity Framework 기능을 조정하는 주 클래스입니다. Microsoft.EntityFrameworkCore.DbContext 클래스에서 파생시키는 방식으로 이 클래스를 만듭니다.

솔루션 탐색기에서 Models 폴더를 마우스 오른쪽 단추로 클릭하고 추가 > 클래스를 선택합니다. 클래스 이름을 TodoContext로 지정하고 추가를 클릭합니다.

클래스를 다음 코드로 바꿉니다.

using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models
{
    public class TodoContext : DbContext
    {
        public TodoContext(DbContextOptions<TodoContext> options)
            : base(options)
        {
        }

        public DbSet<TodoItem> TodoItems { get; set; }
    }
}

데이터베이스 컨텍스트 등록

이 단계에서 데이터베이스 컨텍스트는 종속성 주입 컨테이너에 등록됩니다. DI(종속성 주입) 컨테이너에 등록된 서비스(예: DB 컨텍스트)를 컨트롤러에서 사용할 수 있습니다.

종속성 주입에 대한 기본 제공 지원을 사용하여 서비스 컨테이너에 DB 컨텍스트를 등록합니다. Startup.cs 파일의 내용을 다음 코드로 바꿉니다.

[!code-csharp]

위의 코드:

사용되지 않는 코드를 제거합니다.
메모리 내 데이터베이스를 서비스 컨테이너에 주입하도록 지정합니다.

컨트롤러 추가

솔루션 탐색기에서 Controllers 폴더를 마우스 오른쪽 단추로 클릭합니다. 추가 > 새 항목을 선택합니다. 새 항목 추가 대화 상자에서 API 컨트롤러 클래스 템플릿을 선택합니다. 클래스 이름을 TodoController로 지정하고 추가를 클릭합니다.

클래스를 다음 코드로 바꿉니다.

[!code-csharp]

앞의 코드는 메서드 없이 API 컨트롤러 클래스를 정의합니다. 다음 섹션에서는 API를 구현하기 위해 메서드가 추가됩니다.

컨트롤러의 생성자는 종속성 주입을 통해 컨트롤러에 데이터베이스 컨텍스트(TodoContext)를 삽입할 수 있습니다. 컨트롤러의 CRUD 메서드 각각에서 데이터베이스 컨텍스트를 사용합니다. 항목이 없는 경우 생성자는 메모리 내 데이터베이스에 항목을 추가합니다.

할 일 항목 가져오기

할 일 항목을 가져오려면 다음 메서드를 TodoController 클래스에 추가합니다.

[!code-csharp]

다음과 같은 메서드는 두 개의 GET 메서드를 구현합니다.

GET /api/todo
GET /api/todo/{id}

다음은 GetAll 메서드에 대한 샘플 HTTP 응답입니다.

JSON

[
  {
    "id": 1,
    "name": "Item1",
    "isComplete": false
  }
]

자습서의 뒷부분에서는 HTTP 응답을 Postman 또는 curl로 볼 수 있는 방법을 설명합니다.

라우팅 및 URL 경로

[HttpGet] 특성은 HTTP GET 요청에 응답하는 메서드를 나타냅니다. 각 방법에 대한 URL 경로는 다음과 같이 구성됩니다.

컨트롤러의 Route 특성에서 템플릿 문자열을 사용합니다.

[!code-csharp]

[controller]를 컨트롤러의 이름으로 바꿉니다. 즉, 컨트롤러 클래스 이름에서 “Controller” 접미사를 뺀 이름입니다. 이 샘플의 경우 컨트롤러 클래스 이름은 TodoController이고 루트 이름은 “todo”입니다. ASP.NET Core 라우팅은 대/소문자를 구분하지 않습니다.
[HttpGet] 특성에 경로 템플릿(예: [HttpGet("/products")])이 있는 경우 경로에 추가합니다. 이 샘플은 템플릿을 사용하지 않습니다. 자세한 내용은 Http[동사] 특성을 사용한 특성 라우팅을 참조하세요.

다음 GetById 메서드에서 "{id}"는 할 일 항목의 고유 식별자에 대한 자리 표시자 변수입니다. GetById가 호출되면 URL의 "{id}" 값을 메서드의 id 매개 변수에 할당합니다.

[!code-csharp]

Name = "GetTodo"는 명명된 경로를 만듭니다. 명명된 경로:

앱에서 해당 경로 이름을 사용하여 HTTP 링크를 만들도록 설정합니다.
자습서의 뒷부분에서 설명합니다.

반환 값

GetAll 메서드는 TodoItem 개체의 컬렉션을 반환합니다. MVC는 자동으로 JSON에 개체를 직렬화하고 JSON을 응답 메시지의 본문에 기록합니다. 이 메서드의 응답 코드는 200이며 처리되지 않은 예외가 없다고 가정합니다. 처리되지 않은 예외는 5xx 오류로 변환됩니다.

반면, GetById 메서드는 다양한 반환 형식을 나타내는 보다 일반적인 IActionResult 형식을 반환합니다. GetById에는 두 개의 다른 반환 형식이 있습니다.

요청된 ID와 일치하는 항목이 없는 경우 메서드가 404 오류를 반환합니다. NotFound를 반환하면 HTTP 404 응답이 반환됩니다.
그렇지 않으면 메서드가 JSON 응답 본문에서 200을 반환합니다. 확인을 반환하면 HTTP 200 응답이 발생합니다.

앱 시작

Visual Studio에서 CTRL+F5를 눌러 앱을 시작합니다. Visual Studio가 브라우저를 시작하고 http://localhost:<port>/api/values로 이동합니다. 여기서 <port>는 임의로 선택된 포트 번호입니다. http://localhost:<port>/api/todo의 Todo 컨트롤러로 이동합니다.

기타 CRUD 작업 구현

다음 섹션에서 Create, Update 및 Delete 메서드가 컨트롤러에 추가됩니다.

만들기

다음 Create 메서드를 추가합니다.

[!code-csharp]

이전 코드는 [HttpPost] 특성으로 표시되는 HTTP POST 메서드입니다. [FromBody] 특성은 HTTP 요청 본문에서 할 일 항목 값을 가져오도록 MVC에 지시합니다.

CreatedAtRoute 메서드는 다음과 같은 작업을 수행합니다.

201 응답을 반환합니다. HTTP 201은 서버에서 새 리소스를 만드는 HTTP POST 메서드의 표준 응답입니다.
응답에 대한 위치 헤더를 추가합니다. 위치 헤더는 새로 만들어진 할 일 항목의 URI를 지정합니다. 10.2.2 201 Created(10.2.2 201 생성됨)를 참조하세요.
“GetTodo”라는 경로를 사용하여 URL을 만듭니다. “GetTodo”라는 경로는 GetById에 정의됩니다.

[!code-csharp]

Postman을 사용하여 만들기 요청 보내기

응용 프로그램을 시작합니다.
Postman을 엽니다.

localhost URL에서 포트 번호를 업데이트합니다.
HTTP 메서드를 POST로 설정합니다.
본문 탭을 클릭합니다.
원시 라디오 단추를 선택합니다.
JSON (application/json) 으로 유형을 설정합니다.
다음 JSON과 같은 할 일 항목을 사용하여 요청 본문을 입력합니다.

JSON

{
  "name":"walk dog",
  "isComplete":true
}

보내기 단추를 클릭합니다.

응답 창에서 헤더 탭을 클릭하고 위치 헤더 값을 복사합니다.

위치 헤더 URI를 사용하여 새 항목에 액세스할 수 있습니다.

업데이트

다음 Update 메서드를 추가합니다.

[!code-csharp]

HTTP PUT을 사용하는 것을 제외하고 Update는 Create와 비슷합니다. 응답은 204(콘텐츠 없음)입니다. HTTP 사양에 따라 PUT 요청의 경우 클라이언트는 델타만이 아니라 전체 업데이트된 엔터티를 보내야 합니다. 부분 업데이트를 지원하려면 HTTP PATCH를 사용합니다.

Postman을 사용하여 할 일 항목의 이름을 “walk cat”으로 업데이트합니다.

삭제

다음 Delete 메서드를 추가합니다.

[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
    var todo = _context.TodoItems.Find(id);
    if (todo == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todo);
    _context.SaveChanges();
    return NoContent();
}

Delete 응답은 204(콘텐츠 없음)입니다.

Postman을 사용하여 할 일 항목을 삭제합니다.

jQuery를 사용하여 Web API 호출

이 섹션에서는 jQuery를 사용하여 Web API를 호출하는 HTML 페이지가 추가되었습니다. jQuery는 요청을 시작하고 API 응답의 세부 정보로 페이지를 업데이트합니다.

정적 파일을 제공하고 기본 파일 매핑을 사용하도록 프로젝트를 구성합니다. 이는 Startup.Configure에서 UseStaticFiles 및 UseDefaultFiles 확장 메서드를 호출하여 수행됩니다. 자세한 내용은 정적 파일을 참조하세요.

public void Configure(IApplicationBuilder app)
{
    app.UseDefaultFiles();
    app.UseStaticFiles();
    app.UseMvc();
}

index.html이라는 HTML 파일을 해당 프로젝트의 wwwroot 디렉터리에 추가합니다. 다음 표시로 콘텐츠를 바꿉니다.

HTML

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>To-do CRUD</title>
    <style>
        input[type='submit'], button, [aria-label] {
            cursor: pointer;
        }

        #spoiler {
            display: none;
        }

        table {
            font-family: Arial, sans-serif;
            border: 1px solid;
            border-collapse: collapse;
        }

        th {
            background-color: #0066CC;
            color: white;
        }

        td {
            border: 1px solid;
            padding: 5px;
        }
    </style>
</head>
<body>
    <h1>To-do CRUD</h1>
    <h3>Add</h3>
    <form action="javascript:void(0);" method="POST" onsubmit="addItem()">
        <input type="text" id="add-name" placeholder="New to-do">
        <input type="submit" value="Add">
    </form>

    <div id="spoiler">
        <h3>Edit</h3>
        <form class="my-form">
            <input type="hidden" id="edit-id">
            <input type="checkbox" id="edit-isComplete">
            <input type="text" id="edit-name">
            <input type="submit" value="Edit">
            <a onclick="closeInput()" aria-label="Close">&#10006;</a>
        </form>
    </div>

    <p id="counter"></p>

    <table>
        <tr>
            <th>Is Complete</th>
            <th>Name</th>
            <th></th>
            <th></th>
        </tr>
        <tbody id="todos"></tbody>
    </table>

    <script src="https://code.jquery.com/jquery-3.3.1.min.js"
            integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="
            crossorigin="anonymous"></script>
    <script src="site.js"></script>
</body>
</html>

site.js라는 JavaScript 파일을 해당 프로젝트의 wwwroot 디렉터리에 추가합니다. 다음 코드로 콘텐츠를 바꿉니다.

JavaScript

const uri = 'api/todo';
let todos = null;
function getCount(data) {
    const el = $('#counter');
    let name = 'to-do';
    if (data) {
        if (data > 1) {
            name = 'to-dos';
        }
        el.text(data + ' ' + name);
    } else {
        el.html('No ' + name);
    }
}

$(document).ready(function () {
    getData();
});

function getData() {
    $.ajax({
        type: 'GET',
        url: uri,
        success: function (data) {
            $('#todos').empty();
            getCount(data.length);
            $.each(data, function (key, item) {
                const checked = item.isComplete ? 'checked' : '';

                $('<tr><td><input disabled="true" type="checkbox" ' + checked + '></td>' +
                    '<td>' + item.name + '</td>' +
                    '<td><button onclick="editItem(' + item.id + ')">Edit</button></td>' +
                    '<td><button onclick="deleteItem(' + item.id + ')">Delete</button></td>' +
                    '</tr>').appendTo($('#todos'));
            });

            todos = data;
        }
    });
}

function addItem() {
    const item = {
        'name': $('#add-name').val(),
        'isComplete': false
    };

    $.ajax({
        type: 'POST',
        accepts: 'application/json',
        url: uri,
        contentType: 'application/json',
        data: JSON.stringify(item),
        error: function (jqXHR, textStatus, errorThrown) {
            alert('here');
        },
        success: function (result) {
            getData();
            $('#add-name').val('');
        }
    });
}

function deleteItem(id) {
    $.ajax({
        url: uri + '/' + id,
        type: 'DELETE',
        success: function (result) {
            getData();
        }
    });
}

function editItem(id) {
    $.each(todos, function (key, item) {
        if (item.id === id) {
            $('#edit-name').val(item.name);
            $('#edit-id').val(item.id);
            $('#edit-isComplete').val(item.isComplete);
        }
    });
    $('#spoiler').css({ 'display': 'block' });
}

$('.my-form').on('submit', function () {
    const item = {
        'name': $('#edit-name').val(),
        'isComplete': $('#edit-isComplete').is(':checked'),
        'id': $('#edit-id').val()
    };

    $.ajax({
        url: uri + '/' + $('#edit-id').val(),
        type: 'PUT',
        accepts: 'application/json',
        contentType: 'application/json',
        data: JSON.stringify(item),
        success: function (result) {
            getData();
        }
    });

    closeInput();
    return false;
});

function closeInput() {
    $('#spoiler').css({ 'display': 'none' });
}

HTML 페이지를 로컬에서 테스트하려면 ASP.NET Core 프로젝트의 시작 설정을 변경해야 할 수 있습니다. 프로젝트의 속성 디렉터리에서 launchSettings.json을 엽니다. launchUrl 속성을 제거하여 앱이 index.html— 프로젝트의 기본 파일에서 열리도록 합니다.

여러 가지 방법으로 jQuery를 가져올 수 있습니다. 위의 코드 조각에서 라이브러리는 CDN에서 로드됩니다. 이 샘플은 jQuery를 사용하여 API를 호출하는 완전한 CRUD 예제입니다. 이 샘플에는 경험을 풍부하게 하는 추가 기능이 있습니다. 다음은 API 호출에 대한 설명입니다.

할 일 항목의 목록 가져오기

할 일 항목의 목록을 가져오려면 HTTP GET 요청을 /api/todo에 보냅니다.

jQuery ajax 함수는 개체 또는 배열을 나타내는 JSON을 반환하는 API에 AJAX 요청을 보냅니다. 이 함수는 HTTP 요청을 지정된 url로 보내는 모든 형태의 HTTP 상호 작용을 처리할 수 있습니다. GET이 type으로 사용됩니다. 요청이 성공하면 success 콜백 함수가 호출됩니다. 콜백에서 DOM은 할 일 정보로 업데이트됩니다.

JavaScript

$(document).ready(function () {
    getData();
});

function getData() {
    $.ajax({
        type: 'GET',
        url: uri,
        success: function (data) {
            $('#todos').empty();
            getCount(data.length);
            $.each(data, function (key, item) {
                const checked = item.isComplete ? 'checked' : '';

                $('<tr><td><input disabled="true" type="checkbox" ' + checked + '></td>' +
                    '<td>' + item.name + '</td>' +
                    '<td><button onclick="editItem(' + item.id + ')">Edit</button></td>' +
                    '<td><button onclick="deleteItem(' + item.id + ')">Delete</button></td>' +
                    '</tr>').appendTo($('#todos'));
            });

            todos = data;
        }
    });
}

할 일 항목 추가

할 일 항목을 추가하려면 HTTP POST 요청을 /api/todo/ 에 보냅니다. 요청 본문은 할 일 개체를 포함해야 합니다. ajax 함수는 POST를 사용하여 API를 호출합니다. POST 및 PUT 요청의 경우, 요청 본문은 API에 전송되는 데이터를 나타냅니다. API는 JSON 요청 본문을 요구합니다. accepts 및 contentType 옵션은 수신 및 전송되는 미디어 유형을 각각 분류하기 위해 application/json으로 설정됩니다. 데이터는 JSON.stringify를 사용하여 JSON 개체로 변환됩니다. API가 성공적인 상태 코드를 반환하면 getData 함수가 호출되어 HTML 테이블을 업데이트합니다.

JavaScript

function addItem() {
    const item = {
        'name': $('#add-name').val(),
        'isComplete': false
    };

    $.ajax({
        type: 'POST',
        accepts: 'application/json',
        url: uri,
        contentType: 'application/json',
        data: JSON.stringify(item),
        error: function (jqXHR, textStatus, errorThrown) {
            alert('here');
        },
        success: function (result) {
            getData();
            $('#add-name').val('');
        }
    });
}

할 일 항목 업데이트

할 일 항목을 업데이트하는 것은 할 일 항목을 추가하는 것과 매우 유사합니다. 두 작업 모두 요청 본문에 의존하기 때문입니다. 이 경우 두 작업의 유일한 차이점은 항목의 고유 식별자를 추가하기 위해 url이 변경되고, type은 PUT입니다.

JavaScript

$.ajax({
    url: uri + '/' + $('#edit-id').val(),
    type: 'PUT',
    accepts: 'application/json',
    contentType: 'application/json',
    data: JSON.stringify(item),
    success: function (result) {
        getData();
    }
});

할 일 항목 삭제

할 일 항목을 삭제하려면 AJAX 호출에서 type을 DELETE로 설정하고 URL에서 항목의 고유 식별자를 지정하면 됩니다.

JavaScript

$.ajax({
    url: uri + '/' + id,
    type: 'DELETE',
    success: function (result) {
        getData();
    }
});

배포방법