The API with Steeple - General documentation

Welcome to Steeple APIs

Why Steeple APIs?

Steeple offers several REST APIs intended to improve the integration of Steeple into an existing ecosystem, exploit its resources for dedicated uses or even promote the creation of content from third-party systems.

The Steeple APIs are currently under construction and new features and opportunities will be unveiled over time.

Prerequisites

To use the Steeple APIs, several prerequisites are necessary:

• Have an active account on Steeple: https://steeple.com/fr/ 
• Be member of a community associated with an organization
• Have the “Administrator” role on this community

API URL

All requests to Steeple APIs must necessarily start with:

https://api.steeple.com 

Documentation technique

The detailed technical documentation (type swagger) is available here:

https://api-docs.steeple.com/ 

Authentication

Authentication token

An authentication token is required for each request sent. The authentication token is a long string of characters built by Steeple which can look like:

This authentication token is used to know who calls the APIs and to verify that only permitted resources can be accessed.

Get your authentication token

Nothing could be simpler, for that, you have to go to Steeple. As a community administrator (see prerequisites), you must go to the administration page:

Then navigate to the “Integrations” menu:

Then configure access to Steeple APIs:

Generate a new authentication token:

Fill in the characteristics of the authentication token:

Your authentication token is available.

Authentication format

The authentication token is used asBearer token and must be present in all headers of requests sent to Steeple APIs. Example :

curl 'https://api.steeple.com/v1/posts?page=2&per_page=1' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2ODMyXXX2MTYsInN1YiI6ImYzNjU0ODgwLTM0YzAtNGQ4Yi04OWU4LWEzNGU2MTE1YTM3NSJ9.eOpVocgU1Pzapnj3iFc6RzqWi3V63_xnXEb_AwDF-dk'

Scope of accessible data

The accessible data is limited to the scope of the organization for which the authentication token was generated.

Timezone

All dates are expressed in ISO8601 format based on UTC. Example :

2023-03-22T13:08:55Z

Troubleshooting

Basic principles

Steeple APIs use standardized HTTP error codes. Each HTTP error code is accompanied by a key specifying the nature of the error encountered, which can vary from one API to another.

Authentication errors

Below, the main cases of errors related to authentication:

Code HTTP	message error	Case of error
401	Unauthorized	The authentication token provided does not allow authentication on Steeple. Check authentication token. If necessary, generate a new authentication token.
403	Forbidden	The authentication token provided allows authentication but has been revoked.Generating a new authentication token is requiredIt is

Common errors

Below are the main error cases, refer to the API description for information on specific errors:

Code HTTP	message error	Case of error
400	Bad Request	The request is just formed or does not contain the information required to carry out the processing requested. Check the data transmitted in the request. Contact support if needed.
404	Not Found	The request refers to a resource that cannot be found. Check the data transmitted in the request. Contact support if needed.
422	Unprocessable entity	The request provides incomplete or incomprehensible information. Check the data transmitted in the request.
500	Internal Server Error	The server is unable to process the request. Replay the request later, if the problem persists, contact support.

Glossary

Organisation  (Organization)

The organization represents your context in Steeple. Everything in this organization is available to you. However, you cannot access resources belonging to another organization. An organization is associated with at least one community. While in most cases an organization only has one community, some customer contexts require many communities. The resources of all the communities associated with this organization are therefore accessible to someone from this organization.

Community  (Community)

The community is a set of users (members) grouped together and sharing a lot of information (publications, events, modules, etc.). A community can be associated directly with an organization, or, in the context of a daughter community, with another community.

Categories (Groups)

Categories are used in communities to store and organize publications.

User (User)

A Steeple user is a natural person who has an active account on Steeple and who is a member of a community and therefore of an organization. A user can interact with many resources in Steeple (Posts, comments, polls, etc.) but only users with an “Administrator” profile can manage communities. It is also these administrator profiles that can manage authentication tokens.

Authentication token (Access Token)

The authentication token allows a system wishing to request the Steeple APIs to authenticate itself. The authentication token is generated by Steeple and verified with each request received. Verification also allows you to validate the resources that are accessible or not.

Publication (Post)

A post is content shared to one or more communities.It is composed of a title, a description and media. It is nominative, that is to say that it is necessarily associated with an author, namely, a user of the community. A publication is necessarily associated with a category.

Average (Media)

The media accompany the publications in order to enrich the shared content. It can be images, videos or PDF files..