laravel api handler

라라벨 API 핸들러

이 도우미 패키지는 REST-API 요청의 URL을 구문 분석하는 기능을 제공합니다.

설치

참고: 이 버전은 Laravel 5용입니다. Laravel 4를 사용하는 경우 버전 0.4.x를 사용해야 합니다.

다음을 실행하여 작곡가를 통해 패키지를 설치합니다.

 composer require marcelgwerder/laravel-api-handler

작성기가 완료되면 서비스 제공자를 app/config/app.php 의 providers 배열에 추가하십시오.

 MarcelgwerderApiHandlerApiHandlerServiceProvider::class,

이제 ApiHandler 파사드를 클래스로 가져옵니다.

 use Marcelgwerder  ApiHandler  Facades  ApiHandler ;

또는 app.php 에 별칭을 설정하세요.

 'ApiHandler' => MarcelgwerderApiHandlerFacadesApiHandler::class,

그게 다야!

0.3.x에서 >= 0.4.x로 마이그레이션

관계 주석

이제 관계 메서드는 다른 메서드가 아닌 관계 메서드임을 증명하기 위해 @Relation 주석이 필요합니다(문제 #11 참조).

 /**
 * @Relation
 */
public function author () {
    return $ this -> belongsTo ( ' Author ' );  
}

사용자 정의 식별 열

parseSingle 에 두 번째 매개변수로 배열을 전달하는 경우 이제 열/값 쌍이 있어야 합니다. 이를 통해 다음과 같은 여러 조건을 전달할 수 있습니다.

 ApiHandler :: parseSingle ( $ books , array ( ' id_origin ' => ' Random Bookstore Ltd ' , ' id ' => 1337 ));

구성

구성을 재정의하려면 앱의 config 폴더에 apihandler.php 라는 파일을 만듭니다.
어떤 옵션을 사용할 수 있는지 보려면 패키지 소스의 구성 파일을 확인하세요.

URL 분석

URL 구문 분석은 현재 다음을 지원합니다.

• 필드 제한
• 필터링
• 전체 텍스트 검색
• 정렬
• 한계 및 오프셋 정의
• 관련 모델 추가
• 메타 정보 추가(개수)

지원되는 API 리소스에는 단일 객체와 객체 컬렉션의 두 가지 유형이 있습니다.

단일 객체

예를 들어 /api/books/1 과 같이 단일 객체를 나타내는 리소스에 대한 GET 요청을 처리하는 경우, parseSingle 메서드를 사용하세요.

파싱싱글($queryBuilder, $identification, [$queryParams]):

• $queryBuilder : 쿼리 빌더 객체, Eloquent 모델 또는 Eloquent 관계
• $identification : 객체의 고유 식별자로 사용되는 id 열 또는 배열 열/값 쌍( array('isbn' => '1234') )에 사용되는 정수입니다.
• $queryParams : 쿼리 매개변수가 포함된 배열입니다. 정의되지 않은 경우 원래 GET 매개변수가 사용됩니다.

 ApiHandler :: parseSingle ( $ book , 1 );

객체 수집

예를 들어 /api/books 와 같이 여러 객체를 나타내는 리소스에 대한 GET 요청을 처리하는 경우에는 parseMultiple 메서드를 사용하세요.

ParseMultiple($queryBuilder, $fullTextSearchColumns, [$queryParams]):

• $queryBuilder : 쿼리 빌더 객체, Eloquent 모델 또는 Eloquent 관계
• $fullTextSearchColumns : 전체 텍스트 검색에 사용되는 열을 정의하는 배열입니다.
• $queryParams : 쿼리 매개변수가 포함된 배열입니다. 정의되지 않은 경우 원래 GET 매개변수가 사용됩니다.

 ApiHandler :: parseMultiple ( $ book , array ( ' title ' , ' isbn ' , ' description ' ));

결과

parseSingle 과 parseMultiple 모두 다음 메소드를 사용하여 Result 객체를 반환합니다.

getBuilder(): 모든 함수가 적용된 원본 $queryBuilder 반환합니다.

getResult(): Laravel의 get() 또는 first() 함수에서 반환된 결과 객체를 반환합니다.

getResultOrFail(): 여러 객체가 필요한 경우 Laravel의 get() 함수가 반환한 결과 객체를 반환하고, 단일 객체가 필요한 경우 firstOrFail() 반환한 결과 객체를 반환합니다.

getResponse($resultOrFail = false): 본문, 헤더 및 HTTP 상태 코드를 포함하는 Laravel Response 개체를 반환합니다. $resultOrFail 이 true이면 getResult() 대신 getResultOrFail() 메서드가 내부적으로 사용됩니다.

getHeaders(): 준비된 헤더의 배열을 반환합니다.

getMetaProviders(): 메타 제공자 객체의 배열을 반환합니다. 이러한 각 객체는 get() 메서드를 통해 특정 유형의 메타데이터를 제공합니다.

cleanup($cleanup): true인 경우 결과 배열은 의도하지 않게 추가된 관계에서 정리됩니다. 이러한 관계는 모델 접근자의 속성으로 액세스되는 경우 자동으로 추가될 수 있습니다. 정리에 대한 전역 기본값은 기본값이 false 인 cleanup_relations 구성 옵션을 사용하여 정의할 수 있습니다.

 ApiHandler :: parseSingle ( $ books , 42 )-> cleanup ( true )-> getResponse ();

필터링

사전 정의된 함수 _fields , _with , _sort , _limit , _offset , _config 및 _q 를 제외한 모든 쿼리 매개변수는 필터로 해석됩니다. 필터링용이 아닌 추가 매개변수를 구문 parseMultiple 에 전달하기 전에 제거해야 합니다.

 /api/books?title=The Lord of the Rings

모든 필터는 AND 연산자로 결합됩니다.

 /api/books?title-lk=The Lord*&created_at-min=2014-03-14 12:55:02

위의 예에서는 다음과 같은 SQL이 생성됩니다.

 WHERE ` title ` LIKE " The Lord% " AND ` created_at ` >= " 2014-03-14 12:55:02 "

하나의 필터에 여러 값을 사용하는 것도 가능합니다. 여러 값은 파이프로 구분됩니다 | . 여러 값은 -not 접미사가 있는 경우를 제외하고 OR 로 결합되며 그런 다음 AND 로 결합됩니다. 예를 들어 ID가 5 또는 6인 모든 책은 다음과 같습니다.

 /api/books?id=5|6

또는 ID가 5 또는 6인 책을 제외한 모든 책:

 /api/books?id-not=5|6

-in 접미사를 사용하여 동일한 결과를 얻을 수 있습니다.

 /api/books?id-in=5,6

각각 not-in 접미사는 다음과 같습니다.

 /api/books?id-not-in=5,6

접미사

접미사	연산자	의미
-lk	좋다	SQL LIKE 연산자와 동일
-not-lk	좋아하지 않는다	SQL NOT LIKE 연산자와 동일
-안에	안에	SQL IN 연산자와 동일
-안에서	없음	SQL NOT IN 연산자와 동일
-분	>=	이상
-최대	<=	보다 작거나 같음
-성	<	보다 작음
-gt	>	보다 큼
-아니다	!=	같지 않음

정렬

오름차순과 내림차순의 두 가지 정렬 방법이 있습니다. 내림차순으로 정렬되어야 하는 모든 열은 항상 - 로 시작합니다.

 /api/books?_sort=-title,created_at

전문 검색

전체 텍스트 검색의 두 가지 구현이 지원됩니다. 구성 파일의 fulltext 옵션을 default 또는 native 로 변경하여 사용할 항목을 선택할 수 있습니다.

참고: 빈 _q 매개변수를 사용하면 검색은 항상 빈 결과를 반환합니다.

제한된 사용자 정의 구현(기본값)

주어진 텍스트는 키워드로 분할되어 데이터베이스에서 검색됩니다. 키워드 중 하나가 존재할 때마다 해당 행이 결과 세트에 포함됩니다.

 /api/books?_q=The Lord of the Rings

위의 예에서는 해당 열 중 하나에 The , Lord , of , the , Rings 키워드 중 하나가 포함된 모든 행을 반환합니다. 전체 텍스트 검색에서 고려할 열은 parseMultiple 로 전달됩니다.

네이티브 MySQL 구현

MySQL 버전이 사용하는 엔진에 대한 전체 텍스트 검색을 지원하는 경우 API 핸들러에서 이 고급 검색을 사용할 수 있습니다.
fulltext 구성 옵션을 native 으로 변경하고 parseMultiple 에 전달한 열에 적절한 전체 텍스트 인덱스가 있는지 확인하세요.

각 결과에는 검색어와 일치하는 정도에 따라 결과를 정렬할 수 있는 _score 열도 포함됩니다. 예:

 /api/books?_q=The Lord of the Rings&_sort=-_score

구성 파일에서 fulltext_score_column 설정을 수정하여 이 열의 이름을 조정할 수 있습니다.

결과 세트 제한

결과의 최대 데이터세트 양을 정의하려면 _limit 사용하세요.

 /api/books?_limit=50

결과에서 데이터세트의 오프셋을 정의하려면 _offset 사용하세요.

 /api/books?_offset=20&_limit=50

offset 사용하려면 항상 limit 도 지정해야 한다는 점에 유의하세요. MySQL은 제한 없이 오프셋 정의에 대해 오류를 발생시킵니다.

관련 모델 포함

API 핸들러는 Eloquent 관계도 지원합니다. 따라서 저자와 함께 모든 책을 가져오려면 저자를 _with 매개변수에 추가하기만 하면 됩니다.

 /api/books?_with=author

관계는 중첩될 수도 있습니다.

 /api/books?_with=author.awards

이것이 작동하려면 다음과 같이 각 관계 메소드에 @Relation 주석을 추가해야 합니다.

 /**
 * @Relation
 */
public function author () {
    return $ this -> belongsTo ( ' Author ' );  
}

이는 보안상의 이유로 필요하므로 _with 사용하여 실제 관계 메서드만 호출할 수 있습니다.

참고: _with 와 함께 _fields 사용하여 필드를 제한할 때마다. 내부적으로는 관계의 기본/외부 키를 사용하여 필드를 확장합니다. Eloquent는 관련 모델을 얻으려면 연결 키가 필요합니다.

메타 정보 포함

응답에 추가 정보를 추가할 수 있습니다. 현재 응답 헤더에 추가할 수 있는 개수에는 두 가지 유형이 있습니다.

리소스의 모든 요소 수를 나타내는 total-count , 더 구체적으로 말하면 원래 전달된 쿼리 빌더 인스턴스의 개수입니다. 필터를 추가로 고려하는 filter-count 입니다. 예를 들어 페이지 매김을 구현하는 데 유용할 수 있습니다.

 /api/books?id-gt=5&_config=meta-total-count,meta-filter-count

모든 메타 필드는 기본적으로 응답 헤더에 제공됩니다. 다음 사용자 정의 헤더가 사용됩니다.

구성	헤더
메타 총 개수	메타 총 개수
메타 필터 수	메타 필터 수

답변에는 봉투를 사용하세요

기본적으로 메타데이터는 응답 헤더에 포함됩니다. 응답 본문에 모든 것을 함께 포함하려면 _config 매개변수에 response-envelope 포함하거나 패키지의 기본 config.php 재정의하여 소위 "봉투"를 요청할 수 있습니다.

봉투의 구조는 다음과 같습니다.

{
  "meta" : {

  },
  "data" : [

  ]
}