Restful API guide

1. RESTful API Design Guide 김 병 부 (Benjamin Kim) byungboor@naver.com http://myboor.tistory.com

2. Introspection • Resource의 나열 – RESTful의 본질 외면 – CRUD 제외한 operation 에 대한 어려움 – 수많은 Resource • 보안상 문제점 – Key exchange – 메시지 암호화 X – Error 메시지의 난립 – HTTP Resource에 노출된 정보들 • 통일된 Guide 없이 임기 응변 • OpenAPI가 될 수 없다.

3. Table of Contents • RESTful API fundamental concept • Use RESTful URLs and actions • Error Handling • Security • HATEOAS (optional) • Reference Link

4. RESTful API fundamental concept • Resource – HTTP URL format • Method – HTTP Standard Methods for CRUD operations – POST - Create – GET - Read – DELETE - Delete – PUT - Update • Message – XML, YAML, JSON and HTML format HTTP POST, /instances { “instance” : { “name” : “xmyboor001”, “specId” : “x1.large” } }

5. Use RESTful URLs and actions #1 • 명사를 사용한다. • 복수형을 사용한다. • 구체적인 이름을 사용한다. – (O) HTTP GET /instances – (O) HTTP GET /instances/1024 – (O) HTTP GET /instances/sdcconsoledb01 – (X) HTTP GET /instance – (X) HTTP GET /instances?id=1024 – (X) HTTP GET /getInstance • 예외상황 – CRUD를 제외한 다른 명령어는 어떻게? – E.g. Chef의 Role을 실행하는 경우 (O) HTTP POST /role/2048/run (X) HTTP GET /role/run?instanceId=1024&roleId=2048

6. Use RESTful URLs and actions #2 • 리소스간 관계는 sub-resource를 사용한 다. – HTTP GET /instances/1024/volumes/204 – HTTP POST / instances/1024/volumes • Paging은 limit, offset 키워드를 사용한 다. – Facebook Style – HTTP GET /instances?offset=100&limit=30 • Partial Response (Optional) – Facebook Style – HTTP GET /instances?field=instanceId,name • ER Diagram – Table Instance and Volume

7. Use RESTful URLs and actions #3 Resource GET Read POST Create PUT Update DELETE /instances Returns a list of instances Create a new Instance Bulk update of instances Delete all instances /instances/1024 Returns a specific instance Method not allowed (405 error) Updates a specific instance Delete a specific instance /instances/1024/vol umes Returns a list of volumes of the instance Create a new volume at the instance Bulk update of volumes at the instance Delete all volumes at the instance /instances/1024/vol umes/204 Return a specific volume of the instance Method not allowed (405 error) Update a specific volume at the instance Delete a specific volume at the instance

8. Use RESTful URLs and actions #4 • Searching – 파라미터 이름 ‘q’를 이용한다. – q=name=myboor004,zone=qa&limit=30 – URLEncode 를 사용한다. – HTTP GET /instences?q=name%3Dmyboor004,zone%3D=qa&limit=30 • Sorting – 파라미터 이름 ‘sort’ 를 이용한다. – 기호 ‘-’ descending – 기호 ‘+’ ascending – HTTP GET /instences?sort=-instanceId,+

9. Use RESTful URLs and actions #5 • Version – Mandatory – REST Resource에 정의하는 방법, HTTP Header에 정의 하는 방법 등이 있음 – Resource 에 정의 한다. – HTTP GET /sdc/api/v1.0/instances • HTTP headers for serialization formats – Client, Server 모두 format을 지정해야 한다. – Format은 HTTP-Header의 context-type 을 사용한다. – 기본적으로 JSON format을 사용한다. MessageType Content-Type JSON application/json

10. Use RESTful URLs and actions #6 • eXtended headers for REST API – 다음과 같은 customized 된 추가 헤더를 사용한다. – Mandatory or 401 error – Client Side Header Name Description X-NETMARBLE-LOGINID 로그인 아이디 정보 X-NETMARBLE-CHANNEL OpenAPI에 접속하는 Channel 정보

11. Error Handling #1 • Error 처리는 HTTP Status Code를 사용한다. • 약 70여 개의 HTTP Status Code가 존재 – http://en.wikipedia.org/wiki/Http_error_codes • 다음과 같은 방식으로 HTTP Status Code를 사용한다. – 200 - OK : 성공 (동기식) – 201 - OK : 성공 (비동기식) – 400 - Bad Request : Parameter validation 실패, Json 포멧 에러 – 401 - Unauthorized : 인증 실패 – 403 – Forbidden : 인가 실패 – 404 - Not Found – 410 - Gone : 요청된 resource가 더 이상 존재하지 않을때 발생하는 에러. – 500 - Internal Server Error : 서버 측 에러

12. Error Handling #2 • Error Payload – HTTP Status code 만으로 충분한 메시지가 전달되기 힘들다. – 서버에서는 다음과 같은 format으로 response body에 응답한다. HTTP Status Code : 401 { “status” : “401”, “userMessage” : “Authentication Failure”, “errorCode” : “30201”, “errorInfo” : “http://sdn/wiki/errors/30201” } – 단 2XX code에서는 payload가 필요없다. – Exception Stack 정보를 포함하지 않는다.

13. Security #1 • 인증 (Authentication) – REST API를 호출하는 대상을 확인하는 절차 • 인가 (Authorization) – REST API의 resource를 사용할 권한이 있는지 확인하는 절차 • 네트워크 레벨의 암호화 – 네트워크 프로토콜 단의 암호화. – HTTPS 를 사용한다. • 메시지 무결성 보장 – 메시지 변조를 방지하기 위해서, 메시지의 Hash Code를 비교하여 메시지 무결성을 확인 • 메시지 본문 암호화 – 네트워크 레벨의 암호화를 사용 못하는 경우, 메시지 본문을 암호화한다.

14. Security #2 • Authentication – Basic Authentication 은 가능한 피한다. 계정와 암호를 Base64 인코딩하므로 디코딩 가능함. – Token 방식의 digest algorithm – HMAC-SHA256 – Use OAuth 1.0a or Oauth 2 • API Key를 사용 – Entropy – Reduced Exposure – Traceability – Avoid Sessions – Authenticate every request

15. Security #3 • API Access Token 인증방법 – Use HTTPS – Token exchange using Secure Cookie https://www.owasp.org/index.php/SecureFlag – Access token is valid within expireTime – 조대협님 블로그 (http://bcho.tistory.com/955)

16. Security #4 • REST API Message Policy in Spring MVC – Controller, Service, Dao – ValueObject – Table Record와 일치 > ValueObject 를 JSON 포멧으로 마샬링할 때, 중요한 데이터까지 사용자에게 노출된다. – DomainObject for JSON Message – Controller Layer에서 marshalling, unmarshalling 하기 위해서 Domain 객체를 사용한다.

17. HATEOAS (optional) • HATEOAS – Hypermedia as the engine of application state – HTTP Response에 다음 action에 관한 링크를 제공 – E.g. detail 링크를 제공하는 경우 – E.g. paging 링크를 제공하는 경우 HTTP GET /instances?limit=30&offset=30 { “rows” : [ {“instanceId” : 1024, “name” : “sdcconsoledb01”}, {“instanceId” : 1025, “name” : “sdcconsoledb02”} ], “links” : [ {“rel” : “prev”, “href” : “http://sdc/instances?limit=30&offset=0”}, {“rel” : “next”, “href” : “http://sdc/instances?limit=30&offset=60”} ] }

18. Reference Link • http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/ • http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api • http://restful-api-design.readthedocs.org/en/latest/resources.html • http://www.slideshare.net/stormpath/secure-your-rest-api-the-right-way • http://bcho.tistory.com/914 • http://bcho.tistory.com/953 • http://bcho.tistory.com/955