ArxivRequest
public protocol ArxivRequest
A type providing specification of aXiv API request.
-
Returns full specification of the request.
Conformig type decide and document configuration of the returned specification.
Declaration
Swift
var requestSpecification: ArxivRequestSpecification { get }
-
url
Extension methodReturns URL for making arXiv API calls specified by the request.
Declaration
Swift
var url: URL { get }
-
sorted(by:
Extension method) Returns a new request changing the sorting criterion in
requestSpecification
.Declaration
Swift
func sorted(by sortingCriterion: ArxivRequestSpecification.SortingCriterion) -> ArxivRequest
Parameters
sortCriterion
A sorting criterion.
-
sortingOrder(_:
Extension method) Returns a new request changing the sorting order in
requestSpecification
.Declaration
Swift
func sortingOrder(_ sortingOrder: ArxivRequestSpecification.SortingOrder) -> ArxivRequest
Parameters
sortingOrder
A sorting order.
-
startIndex(_:
Extension method) Returns a new request changing the start index in
requestSpecification
.Use to imlement paging. For example, if
itemsPerPage == 20
, the first page corresponds tostartIndex == 0
, the second page tostartIndex == 40
, the third page tostartIndex == 60
etc.ArxivReponse
values can be used for getting various page indicies for given response.From arxiv API manual:
In cases where the API needs to be called multiple times in a row, we encourage you to play nice and incorporate a 3 second delay in your code.
Because of speed limitations in our implementation of the API, the maximum number of results returned from a single call (
itemsPerPage
) is limited to 30000 in slices of at most 2000 at a time, using theitemsPerPage
andstartIndex
query parameters.For example to retrieve matches 6001-8000:
term("electron", in: .any) .startIndex(6000) .itemsPerPage(8000)
Large result sets put considerable load on the server and also take a long time to render. We recommend to refine queries which return more than 1,000 results, or at least request smaller slices. For bulk metadata harvesting or set information, etc., the OAI-PMH interface is more suitable. A request with
itemsPerPage
> 30,000 will result in an HTTP 400 error code with appropriate explanation. A request for 30000 results will typically take a little over 2 minutes to return a response of over 15MB. Requests for fewer results are much faster and correspondingly smaller.Precondition
i >= 0
Declaration
Swift
func startIndex(_ i: Int) -> ArxivRequest
Parameters
i
Start index of the request.
-
itemsPerPage(_:
Extension method) Returns a new request changing the number of items per single response page in
requestSpecification
.From arxiv API manual:
In cases where the API needs to be called multiple times in a row, we encourage you to play nice and incorporate a 3 second delay in your code.
Because of speed limitations in our implementation of the API, the maximum number of results returned from a single call (
itemsPerPage
) is limited to 30000 in slices of at most 2000 at a time, using theitemsPerPage
andstartIndex
parameters.For example to retrieve matches 6001-8000:
term("electron", in: .any) .startIndex(6000) .itemsPerPage(8000)
Large result sets put considerable load on the server and also take a long time to render. We recommend to refine queries which return more than 1,000 results, or at least request smaller slices. For bulk metadata harvesting or set information, etc., the OAI-PMH interface is more suitable. A request with
itemsPerPage > 30000
will result in anHTTP 400
error code with appropriate explanation. A request for30000
results will typically take a little over 2 minutes to return a response of over 15MB. Requests for fewer results are much faster and correspondingly smaller.Precondition
n > 0
Declaration
Swift
func itemsPerPage(_ n: Int) -> ArxivRequest
Parameters
n
Maximum number of articles per response.
-
fetch(using:
Extension method, asynchronousdelegate: ) Uses provided session to download and parse articles specified by the request and delivers the result asynchronously.
Throws
An error which is either
ArxivURLError
,ArxivServerError
,ArxivParserError
orArxivAPIError
.Declaration
Swift
@available(macOS 12.0.0, iOS 15.0.0, *) func fetch(using session: URLSession, delegate: URLSessionTaskDelegate? = nil) async throws -> ArxivResponse
Parameters
session
An
URLSession
object used for fetching.delegate
A delegate that receives life cycle and authentication challenge callbacks as the transfer progresses.
-
fetchTask(using:
Extension methodcompletion: ) Uses provided session to create and return a task described by the request.
The completion handler takes a single
Result
argument, which is either a succesfuly parsedArxivResponse
or an error, if one occurs. The error is eitherArxivURLError
,ArxivServerError
,ArxivParserError
orArxivAPIError
.If multiple tasks are programatically run in a raw, a 3 seconds delay between the tasks is recomended by arxiv API manual.
Note
Completion handler is called on session’sdelegateQueue
.Declaration
Swift
func fetchTask(using session: URLSession, completion: @escaping ArxivFetchTaskCompetionHandler) -> URLSessionDataTask
Parameters
session
An
URLSession
object used for creating and running the task.completion
A function to be called after the task finishes.
-
fetch(using:
Extension methodcompletion: ) Uses provided session to create and and run a task described by the request. Method returns the task after it starts running.
The completion handler takes a single
Result
argument, which is either a succesfuly parsedArxivResponse
, or anArxivKitError
, if one occurs.If multiple tasks are programatically run in a raw, a 3 seconds delay between the tasks is recomended by arxiv API manual.
Note
Completion handler is called on session’sdelegateQueue
.Declaration
Swift
@discardableResult func fetch(using session: URLSession, completion: @escaping ArxivFetchTaskCompetionHandler) -> URLSessionDataTask
Parameters
session
An
URLSession
object used for creating and running the task.completion
A function to be called after the task finishes.
-
fetchTask(using:
Extension methodassignResultTo: on: ) Uses provided session to create and return a task described by the request.
When the task completes, a result is assigned to property indicated by
keyPath
on the provided object.The result is either a succesfuly parsed
ArxivResponse
or an error, if one occurs. The error is eitherArxivURLError
,ArxivServerError
,ArxivParserError
orArxivAPIError
.Note
The assignment happens on session’sdelegateQueue
.Declaration
Swift
func fetchTask<Root>( using session: URLSession, assignResultTo keyPath: ArxivFetchResultKeypath<Root>, on object: Root ) -> URLSessionDataTask
Parameters
session
An
URLSession
object used for creating and running the task.keyPath
A key path that indicates the property to assign.
object
The object that contains the property.
-
fetch(using:
Extension methodassignResultTo: on: ) Uses provided session to create and and run a task described by the request. Method returns the task after it starts running.
The result is either a succesfuly parsed
ArxivResponse
or an error, if one occurs. The error is eitherArxivURLError
,ArxivServerError
,ArxivParserError
orArxivAPIError
.Note
The assignment happens on session’sdelegateQueue
.Declaration
Swift
@discardableResult func fetch<Root>( using session: URLSession, assignResultTo keyPath: ArxivFetchResultKeypath<Root>, on object: Root ) -> URLSessionDataTask
Parameters
session
An
URLSession
object used for creating and running the task.keyPath
A key path that indicates the property to assign.
object
The object that contains the property.