Caching Example
- how-to
A walk-through of the basics of Key-Value operations with Couchbase, through the lens of a REST api caching layer.
This example uses Flask as a web-framework for a Python REST API. Flask has no direct support for async, but another code sample is available demonstrating this whole application using the Couchbase async API here. You can also find the full code for this example here.
Basic Endpoint
Our first basic endpoints will be a get and set call, using HTTP methods GET and POST and Couchbase methods get and insert respectively:
@app.route('/<key>', methods=['GET'])
def get(key):
try:
res = cb.get(key)
return jsonify(res.content_as[dict])
except DocumentNotFoundException:
return 'Key not found', 404
except CouchbaseException as e:
return 'Unexpected error: {}'.format(e), 500
@app.route('/<key>', methods=['POST'])
def post(key):
try:
cb.insert(key, request.json, expiry=EXPIRY)
return 'OK'
except DocumentExistsException:
return 'Key already exists', 409
except CouchbaseException as e:
return 'Unexpected error: {}'.format(e), 500
This is the simplest API we can make — allowing us to set and get arbitrary JSON from any key we specify.
We also include the expiry parameter, which will automatically delete the document (invalidate the cache) after a set amount of time.
Cache Miss
There are many ways this can and could be improved upon for real world use.
What happens in the case of a cache miss?
The GET endpoint above handles the DocumentNotFoundException and responds with a HTTP 404, which suits a cache that callers fill themselves.
A read-through cache fills itself instead.
On a miss, it fetches the value from the system of record, stores it in Couchbase with the same expiry, and returns it, so the next request for that key is a cache hit:
def fetch_from_source(key):
# Stands in for the system of record the cache sits in front of,
# such as a relational database or a slower upstream service.
return {'id': key, 'fetched_at': datetime.now(timezone.utc).isoformat()}
@app.route('/read-through/<key>', methods=['GET'])
def read_through(key):
try:
return jsonify(cb.get(key).content_as[dict])
except DocumentNotFoundException:
pass
except CouchbaseException as e:
return 'Unexpected error: {}'.format(e), 500
doc = fetch_from_source(key)
if doc is None:
return 'Key not found', 404
try:
cb.upsert(key, doc, expiry=EXPIRY)
except CouchbaseException as e:
# The caller still gets the data; the next miss tries the write again.
app.logger.warning('Could not cache %s: %s', key, e)
return jsonify(doc)
fetch_from_source stands in for whatever the cache sits in front of, such as a relational database or a slower service.
A failure to write the value to the cache is logged rather than returned, because the caller already has the data it asked for.
Error Handling
We can also improve the POST function to deal with some of the errors it may encounter.
Even if something unexpected happens, we can still be helpful by including the error in the 500 response, and by catching any CouchbaseException as a fallback:
@app.route('/<key>', methods=['POST'])
def post(key):
try:
cb.insert(key, request.json, expiry=EXPIRY)
return 'OK'
except DocumentExistsException:
return 'Key already exists', 409
except CouchbaseException as e:
return 'Unexpected error: {}'.format(e), 500
The last thing we’ll do is add PUT and DELETE endpoints, matching up to the Couchbase operations upsert and remove, and apply the same error handling once more:
@app.route('/<key>', methods=['PUT'])
def put(key):
try:
cb.upsert(key, request.json, expiry=EXPIRY)
return 'OK'
except CouchbaseException as e:
return 'Unexpected error: {}'.format(e), 500
@app.route('/<key>', methods=['DELETE'])
def delete(key):
try:
cb.remove(key)
return 'OK'
except DocumentNotFoundException:
# Document already deleted / never existed
return 'Key does not exist', 404
Additional Resources
-
You can find the full contextualized code from this sample here.
-
Selecting an ephemeral or Memcached bucket for the advantages of purely in-memory storage may make sense as a design decision.
-
A webinar, a whitepaper, and other high-level information on choosing Couchbase as a caching layer is on the main Couchbase website.