Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Profile API => Dataset API #52

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
* [Digital Markets Act (DMA) Consent for Ad Platforms](basics/security-and-privacy/dma-consent-for-ad-platforms.md)
* [Developers](basics/developers/README.md)
* [GitLink](basics/developers/gitlink.md)
* [Profile API](basics/developers/entity-api.md)
* [Dataset API](basics/developers/entity-api.md)
* [Custom Destination API](basics/developers/custom-api.md)
* [Management API](basics/developers/api.md)
* [Census Embedded](basics/census-embedded.md)
Expand Down
2 changes: 1 addition & 1 deletion basics/audience-hub/syncing-segments.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,6 @@ In this case, the entity has a dynamic value called **Segment Membership** that

<figure><img src="../../.gitbook/assets/CleanShot 2023-12-13 at [email protected]" alt=""><figcaption><p>Sync "Segment Membership" from the parent entity.</p></figcaption></figure>

You can also sync this field to make segment memberships available via the [Profile API](../developers/entity-api.md).
You can also sync this field to make segment memberships available via the [Dataset API](../developers/entity-api.md).

Syncing Segment Memberships will recalculate segment membership across all syncs for that entity at sync time so depending on the number of segments created, this can slow down your sync.
2 changes: 1 addition & 1 deletion basics/developers/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: Learn more about all the ways to programmatically control Census

Census supports several different APIs for controlling, accessing data, and extending Census. Teams that have the ability to write code can quickly customize Census and make it an even more integrated component of your data infrastructure.

* [Profile API](entity-api.md) - An optional REST API for accessing data stored in your [Entities](../data-models-and-entities/entities.md) on demand.
* [Dataset API](entity-api.md) - An optional REST API for accessing data stored in your [Datasets](../data-models-and-entities/entities.md) on demand.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TODO: update this link when the datasets docs are live.

* [Management API](api.md) - A REST API for controlling the Syncs, Models, and Connections configured within Census. This can be used to programmatically read information and perform most actions available in the Census app today.
* [Custom Destination API](custom-api.md) - A rich JSON-RPC API for implementing your own custom destination for Census Syncs. This API supports batching and schemas just like other Census connections.
* If you're looking for an easy way to send data to a custom destination, you may also want to look at Census's [webhook.md](../../destinations/webhook.md "mention") connector.
Expand Down
35 changes: 17 additions & 18 deletions basics/developers/entity-api.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@
---
description: >-
Unleash your entity graph and use your data to power apps far beyond your data
warehouse.
Turn your datasets into an API with a single click to power real-time personalization and recommendations.
---

# Profile API
# Dataset API

Profile API is designed to make your Entities even more valuable by making them easily accessible to the wider app ecosystem. In addition to using **Census Syncs** to push data to destinations, you can now make your data available to be pulled by your applications.
Dataset API is designed to make your datasets even more valuable by making them easily accessible to the wider app ecosystem. In addition to using **Census Syncs** to push data to destinations, you can now make your data available to be pulled by your applications.

This opens your data to a whole world of data integration possibilities. A few of the most exciting ones include:

Expand All @@ -17,39 +16,39 @@ This opens your data to a whole world of data integration possibilities. A few o
## **Set up**

{% hint style="info" %}
Profile API is available for customers on the Enterprise Plan.&#x20;
Dataset API is available for customers on the Enterprise Plan.&#x20;
{% endhint %}

The Profile API can be enabled for each Census workspace individually. Once enabled, all Entities within that workspace will be available via the API.
The Dataset API can be enabled for each Census workspace individually. Once enabled, all datasets within that workspace will be available via the API.

<figure><img src="../../.gitbook/assets/screely-1677722797342 (1).png" alt=""><figcaption></figcaption></figure>

In order to power the API and make responses quick, Census will automatically cache your entity data on Census managed infrastructure. This process will take a few minutes to hours for extremely large data sets when first enabling the Profile API. Going forward, Census will periodically refresh the cache with incremental changes, just like a typical Census sync. This means that some new data may not be immediately available for querying via the Profile API until the cache is refreshed.
In order to power the API and make responses quick, Census will automatically cache your datasets on Census managed infrastructure. This process will take a few minutes to hours for extremely large datasets when first enabling the API. Going forward, Census will periodically refresh the cache with incremental changes, just like a typical Census sync. This means that some new data may not be immediately available for querying via the Dataset API until the cache is refreshed.

Note that this data will be stored in Census infrastructure until the Profile API is disabled. To learn more about how Census handles your data, see our [Security & Privacy](../security-and-privacy/) page.
Note that this data will be stored on Census infrastructure until the Dataset API is disabled. To learn more about how Census handles your data, see our [Security & Privacy](../security-and-privacy/) page.

## Using Profile API Endpoints
## Using Dataset API Endpoints

**Authentication** - Uses same key as the [Management API](api.md) - This means you shouldn’t use it directly in public code such as javascript on your website. You’ll want to access it server side instead so the key doesn’t leak. A given API key is scoped to a single [Census Workspace](../security-and-privacy/workspaces-and-access-controls.md) and all entities within that workspace will be accessible.
**Authentication** - Uses the same key as the [Management API](api.md). This means you shouldn’t use it directly in public code such as javascript on your website. You’ll want to access it server side instead so the key doesn’t leak. A given API key is scoped to a single [Census Workspace](../security-and-privacy/workspaces-and-access-controls.md) and all datasets within that workspace will be accessible.

API requests should include a standard authentication header of the form:

```
Authentication: bearer <secret-key>
```

The Profile API provides two endpoints:
The Dataset API provides two endpoints:

* List Entities - Provides the set of all entities available via the API
* Get Entity Record - Retrieve a specific record of an entity based on its primary key.
* List Datasets - Provides the set of all datasets available via the API
* Get Dataset Record - Retrieve a specific record of a dataset based on its primary key.

You can also access these APIs directly with our Postman collection.

{% file src="../../.gitbook/assets/Census Profile API Postman Collection.zip" %}
{% file src="../../.gitbook/assets/Census Dataset API Postman Collection.zip" %}

### List Entities
### List Datasets

The List Entities endpoint will return a list of entities that are available through the API as well as their ID which can then be used to construct a query for specific records of an entity type.
The List Datasets endpoint will return a list of datasets that are available through the API as well as their ID which can then be used to construct a query for specific records of a dataset type.

```
GET https://app.getcensus.com/api/v1/entities
Expand Down Expand Up @@ -79,9 +78,9 @@ Response
}
```

### Get Entity Record
### Get Dataset Record

Each entity has its own API endpoint, specific to each. You can see the API on the entities page. You can look up any record of your entity by providing the `record_id`, which will look up the record by matching against the Primary ID column selected in the Entity definition.
Each dataset has its own API endpoint. You can see the API on the datasets page. You can look up any record of your dataset by providing the `record_id`, which will look up the record by matching against the Primary ID column selected in the dataset definition.

The URL will be of the form:

Expand Down
2 changes: 1 addition & 1 deletion basics/security-and-privacy/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ Also, the following data sources _only_ support Basic Sync Engine (as of March 2
* MySQL
* SingleStore

Finally, enabling the Profile API requires us to store the relevant data on our own infrastructure. Census will remove any data stored on your behalf after 14 days of disabling this feature.
Finally, enabling the Dataset API requires us to store the relevant data on our own infrastructure. Census will remove any data stored on your behalf after 14 days of disabling this feature.

## 🤔 Have more questions?

Expand Down