sams.api.service

Example Usage

The SamsApiService provides the base service for APIs to proxy requests to internal services.

Here you will find an example usage of the SamsApiService to add a new endpoint to the API. all:

from superdesk import get_resource_service
from superdesk.resource import Resource
from sams.factory.app import SamsApp
from sams.api.service import SamsApiService

class ApiTestResource(Resource):
    endpoint_name = 'test_resource'
    resource_title = 'test resource'
    url = '/consume/test'
    item_methods = ['GET']
    resource_methods = ['GET']
    schema = {...}

class ApiTestService(SamsApiService):
    pass

def init_app(app: SamsApp):
    ApiTestResource(
        endpoint_name=ApiTestResource.endpoint_name,
        app=app,
        service=ApiTestService(
            get_resource_service('internal_service_name')
        )
    )

Base API Service

class SamsApiService(service: superdesk.services.BaseService)

Sams API Service

Base service for external API endpoints that proxy requests to internal services.

Variables

service (BaseService) – The service to proxy requests to

create(docs: List[Dict[str, Any]], **kwargs) → List[bson.objectid.ObjectId]

Proxy method to create a new document

Removes system attributes using _remove_system_attributes(). Then passes the request to the sams.factory.service.SamsService.post() method of the underlying service.

Parameters

  • docs (list[dict]) – The list of documents to be created

  • kwargs (dict) – Extra arguments to pass onto the underlying service

Return type

list[bson.objectid.ObjectId]

Returns

list og generated IDs for the new documents

update(id: bson.objectid.ObjectId, updates: Dict[str, Any], original: Dict[str, Any]) → Dict[str, Any]

Proxy method to update an existing document

Removes system attributes using _remove_system_attributes(). Then passes the request to the sams.factory.service.SamsService.patch() method of the underlying service

Parameters

  • id (bson.objectid.ObjectId) – ID for the document

  • updates (dict) – Dictionary containing the desired attributes to update

  • original (dict) – Dictionary containing the original document

Return type

dict

Returns

dictionary containing the updated attributes of the document

system_update(id: bson.objectid.ObjectId, updates: Dict[str, Any], original: Dict[str, any])

Not to be used with API Service

Raises

superdesk.errors.SuperdeskApiError –

replace(id: bson.objectid.ObjectId, document: Dict[str, Any], original: Dict[str, Any]) → Dict[str, Any]

Replaces an existing document with a new one

Passes the request to the sams.factory.service.SamsService.replace() method.

Parameters

  • id (bson.objectid.ObjectId) – ID of the document to replace

  • document (dict) – Dictionary containing the original document

  • original (dict) – Dictionary containing the new document

Return type

dict

Returns

dictionary containing the new document

delete(lookup: Dict[str, Any])

Deletes documents based on a lookup query

Passes the request to the sams.factory.service.SamsService.delete() method.

Parameters

lookup (dict) – Lookup used to determine what documents to delete

Returns

The response of the delete action

delete_ids_from_mongo(ids: List[bson.objectid.ObjectId])

Deletes documents in mongo based on their IDs

Passes the request to the sams.factory.service.SamsService.delete_ids_from_mongo() method.

Parameters

ids (list[bson.objectid.ObjectId]) – The list of IDs to delete

Returns

The response of the delete action

delete_docs(docs: List[Dict[str, Any]])

Deletes documents

Passes the request to the sams.factory.service.SamsService.delete_docs() method.

Parameters

docs (list[dict]) – The list of documents to delete

Returns

The response of the delete action

find_one(req: eve.utils.ParsedRequest, **lookup) → Dict[str, Any]

Finds a single document based on request and lookup args

Passes the request to the sams.factory.service.SamsService.find_one() method.

Parameters

  • req (eve.utils.ParsedRequest) – The request object

  • lookup (dict) – Dictionary containing optional lookup arguments

Return type

dict

Returns

The document if found

find(where: Dict[str, Any], **kwargs) → pymongo.cursor.Cursor

Find documents using the provided query arguments

Passes the request to the sams.factory.service.SamsService.find() method.

Parameters

  • where (dict) – Dictionary containing query parameters

  • kwargs (dict) – Dictionary containing optional lookup arguments

Return type

pymongo.cursor.MongoCursor | eve_elastic.elastic.ElasticCursor

Returns

A Mongo or Elastic cursor with the results

get(req: eve.utils.ParsedRequest, lookup: Dict[str, Any])

Find documents using the provided query arguments

Passes the request to the sams.factory.service.SamsService.get() method;

Parameters

  • req (eve.utils.ParsedRequest) – The request object

  • lookup (dict) – Dictionary containing optional lookup arguments

Return type

pymongo.cursor.MongoCursor | eve_elastic.elastic.ElasticCursor

Returns

A Mongo or Elastic cursor with the results

get_from_mongo(req: eve.utils.ParsedRequest, lookup: Dict[str, Any], projection: Optional[Dict[str, Any]] = None) → pymongo.cursor.Cursor

Find documents using MongoDB.

Passes the request to the sams.factory.service.SamsService.get_from_mongo() method.

Parameters

  • req (eve.utils.ParsedRequest) – The request object

  • lookup (dict) – Dictionary containing optional lookup arguments

  • projection (dict) – Dictionary containing optional projection

Return type

pymongo.cursor.MongoCursor

Returns

A Mongo cursor with the results

find_and_modify(**kwargs)

Find and modify documents

Passes the request to the sams.factory.service.SamsService.find_and_modify() method.

Parameters

kwargs –

Returns

The response of the request

search(source: Dict[str, Any]) → eve_elastic.elastic.ElasticCursor

Find documents using Elasticsearch

Passes the request to the sams.factory.service.SamsService.search() method.

Parameters

source (dict) – The source query to pass to Elasticsearch

Return type

ElasticCursor

Returns

An Elasticsearch cursor with the results

Removes a document from Elasticsearch only

Passes the request to the sams.factory.service.SamsService.remove_from_search() method.

Parameters

item (dict) – The document to remove