<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Superface - Medium]]></title>
        <description><![CDATA[Superface is a low-code API framework and infrastructure for discovering, integrating and publishing APIs. - Medium]]></description>
        <link>https://medium.com/superface?source=rss----a27729ffd476---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>Superface - Medium</title>
            <link>https://medium.com/superface?source=rss----a27729ffd476---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Mon, 16 Nov 2026 19:46:55 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/superface" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Turn CV to structured data with GPT-3 and Node.js]]></title>
            <link>https://medium.com/superface/turn-cv-to-structured-data-with-gpt-3-and-node-js-b0d5fd7d716?source=rss----a27729ffd476---4</link>
            <guid isPermaLink="false">https://medium.com/p/b0d5fd7d716</guid>
            <category><![CDATA[tutorial]]></category>
            <category><![CDATA[api-integration]]></category>
            <category><![CDATA[gpt-3]]></category>
            <category><![CDATA[node]]></category>
            <category><![CDATA[workable]]></category>
            <dc:creator><![CDATA[Jan Halama]]></dc:creator>
            <pubDate>Thu, 26 Jan 2023 09:39:33 GMT</pubDate>
            <atom:updated>2023-01-26T09:39:33.141Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XMKKT_MwYxliUv2hzvfvRw.png" /></figure><p>Large language models like GPT-3 are useful to simplify routine tasks. For example, we can take unstructured data, like a job applicant’s resume in PDF, and turn them into structured data and fill them into our Applicant Tracking System (ATS) like Greenhouse or Workable.</p><p>In this article, I will show you a Node.js application which does that. But while GPT-3 simplifies routine data entry jobs, as developers we still need to connect all the respective APIs to download the applicant’s CV, get text from the PDF, and put data to the ATS. Luckily, Superface gets us rid of this routine API wiring. We provide a unified interface across many API providers. Switching from, for example, Workable to Breezy HR, is a one line change.</p><p>Let’s check what steps this application does:</p><ol><li>Loads a CV of a candidate who applied for a given job from an Applicant Tracking System (ATS), like Workable or Greenhouse.</li><li>Converts the CV to text and parses the text into machine-readable data.</li><li>Updates the candidate in the ATS with the data obtained from the CV.</li></ol><p>You can find the complete application in the <a href="https://github.com/superfaceai/cv-analyzer">CV Analyzer repository</a>. It uses the following packages:</p><ul><li><a href="https://www.npmjs.com/package/@superfaceai/one-sdk">@superfaceai/one-sdk</a> — Superface OneSDK is used to integrate with ATS, OpenAI and Cloudmersive SaaS providers.</li><li><a href="https://www.npmjs.com/package/node-fetch">node-fetch</a> — NodeFetch is used to fetch the CV document.</li><li><a href="https://www.npmjs.com/package/dotenv">dotenv</a> — dotenv is used to load environment variables.</li><li><a href="https://www.npmjs.com/package/inquirer">inquirer</a> — Inquirer.js is used to build interactive user interface.</li></ul><p>We also rely on these use cases from <a href="https://superface.ai/catalog">Superface Catalog</a>:</p><p>In this demo we use <a href="https://www.workable.com/">Workable</a> as ATS, <a href="https://cloudmersive.com/">Cloudmersive</a> to convert a candidate’s CV to plain text, and <a href="https://openai.com/">OpenAI</a> provider for conversion of CV to structured data. But you are not limited to just this three providers. For ATS use cases you can use also Breezy HR, Greenhouse and <a href="https://superface.ai/domain/ats">many others</a>.</p><h3>Setting up the application</h3><h4>Clone the app repository and enter its directory</h4><pre>git clone git@github.com:superfaceai/cv-analyzer.git<br>cd cv-analyzer</pre><h4>Install dependencies</h4><pre>npm install</pre><h4>Create accounts (if you do not have them already) for the providers</h4><ul><li>Workable offers <a href="https://www.workable.com/free-trial">15 days free trial</a>. A work e-mail address is required to create the account.</li><li>Cloudmersive has a <a href="https://account.cloudmersive.com/signup">free tier</a> limited to 800 requests per month.</li><li>OpenAI offers a <a href="https://openai.com/api/pricing/">free trial</a> with $18 in free credit usable during the first 3 months.</li></ul><h4>Copy the example .env file</h4><pre>cp .env.example .env</pre><h4>Set credentials and integration parameters for the providers in the .env file</h4><ul><li>Get <a href="https://workable.readme.io/reference/generate-an-access-token#generate-an-api-access-token">Workable Access Token and Subdomain</a>.</li><li>Create Cloudmersive <a href="https://account.cloudmersive.com/keys">Free Tier Key</a>.</li><li>Create OpenAI <a href="https://beta.openai.com/account/api-keys">Secret API Key</a>.</li></ul><h4>Create a job position and add new candidate in Workable ATS</h4><h4>Start the app</h4><p>Once the application starts, it will show you a list of candidates. When you pick one, it will update candidate’s entry with data parsed from their CV.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*i4NKd3WJd9sfkbub" /></figure><h3>How the application works</h3><p>The main flow of the application is in the <a href="https://github.com/superfaceai/cv-analyzer/blob/main/src/index.js">src/index.js</a> file, which calls use cases defined in <a href="https://github.com/superfaceai/cv-analyzer/blob/main/src/use_cases.js">src/use_cases.js</a> file.</p><h4>Selecting the candidate and getting its CV</h4><p>First we list open job positions and candidates for the selected position. This is handled with the <a href="https://superface.ai/recruitment/list-jobs">List Jobs</a> use case; once the user picks a job position, we use <a href="https://superface.ai/recruitment/list-candidates">List Candidates</a> use case with the respective ID of the job position:</p><pre>exports.listCandidates = async (sdk, providerOptions, jobId) =&gt; {<br>  const listCandidatesProfile = await sdk.getProfile(<br>    &#39;recruitment/list-candidates@1.0.0&#39;<br>  );<br>  const listCandidatesResult = await listCandidatesProfile<br>    .getUseCase(&#39;ListCandidates&#39;)<br>    .perform(<br>      {<br>        jobId,<br>      },<br>      providerOptions<br>    );<br>  return listCandidatesResult.unwrap().candidates;<br>};</pre><p>We take the ID of the selected candidate and use the <a href="https://superface.ai/recruitment/get-cv">Get CV</a> use case to obtain the URL of a document with candidate’s resume (typically that’s a PDF, but the ATS may accept other formats as well):</p><pre>exports.getCVUrl = async (sdk, providerOptions, candidateId) =&gt; {<br>  const getCVProfile = await sdk.getProfile(&#39;recruitment/get-cv@1.0.0&#39;);<br>  const getCVResult = await getCVProfile.getUseCase(&#39;GetCV&#39;).perform(<br>    {<br>      candidateId,<br>    },<br>    providerOptions<br>  );<br>  return getCVResult.unwrap().cv.documentUrl;<br>};</pre><h4>Converting CV to text</h4><p>Now we know where the candidate’s CV can be downloaded, but we need to extract the text from it somehow. We use <a href="https://superface.ai/file-conversion/doc-to-text">Convert Document to Text</a> use case for that — we fetch the document and upload it to the conversion provider (Cloudmersive in this example) and get a plain text in return.</p><pre>exports.convertCVToText = async (sdk, providerOptions, cvDocumentUrl) =&gt; {<br>  const docToTextProfile = await sdk.getProfile(<br>    &#39;file-conversion/doc-to-text@1.0.0&#39;<br>  );<br><br>  const fetchDocumentResponse = await fetch(cvDocumentUrl);<br><br>  if (!fetchDocumentResponse.body) {<br>    console.error(&#39;Failed to fetch CV document.&#39;);<br>    return;<br>  }<br><br>  const result = await docToTextProfile<br>    .getUseCase(&#39;ConvertDocumentToText&#39;)<br>    .perform(<br>      {<br>        fileName: &#39;cv.pdf&#39;,<br>        content: BinaryData.fromStream(fetchDocumentResponse.body),<br>      },<br>      providerOptions<br>    );<br><br>  return result.unwrap().text;<br>};</pre><h4>Extracting structured data</h4><p>Now it’s time for some AI magic! We use OpenAI’s GPT-3 model through the <a href="https://superface.ai/ai/generate-text">Text Completion</a> use case. We provide the model with a prompt explaining we need particular data returned as JSON:</p><pre>exports.analyzeCV = async (sdk, providerOptions, cvText) =&gt; {<br>  try {<br>    const generateTextProfile = await sdk.getProfile(&#39;ai/generate-text@1.0.0&#39;);<br><br>    const promptCommand = `Parse following job applicant resume and return json object with properties <br>    { <br>      &quot;firstName&quot;, &quot;lastName&quot;, &quot;address&quot;, &quot;phone&quot;, <br>      &quot;education&quot;:<br>      [{&quot;school&quot;, &quot;fieldOfStudy&quot;, &quot;studiedFrom_ISO8601&quot;:&quot;YYYY-MM-DD&quot;, &quot;studiedTill_ISO8601&quot;:&quot;YYYY-MM-DD&quot;}],<br>    &quot;workHistory&quot;:<br>      [{&quot;company&quot;, &quot;position&quot;, &quot;summary&quot;, &quot;workedFrom_ISO8601:&quot;YYYY-MM-DD&quot;&quot;, &quot;workedTill_ISO8601&quot;:&quot;YYYY-MM-DD&quot;}]<br>    }. `;<br><br>    const result = await generateTextProfile.getUseCase(&#39;CompleteText&#39;).perform(<br>      {<br>        prompt: promptCommand + cvText,<br>        creativity: 0.8,<br>        approxMaxWords: 1000,<br>        model: &#39;large&#39;,<br>      },<br>      providerOptions<br>    );<br><br>    analyzeCVOutcome = result.unwrap();<br>  } catch (error) {<br>    console.error(&#39;Failed to analyze CV.&#39;, error);<br>  }<br>  // ...<br>};</pre><p>If the analysis goes well and the model “completes” our prompt, we turn the returned completion to JSON:</p><pre>const parsedCV = JSON.parse(analyzeCVOutcome.completions[0]);<br>const mappedCV = {<br>  ...parsedCV,<br>  education: parsedCV.education?.map(school =&gt; {<br>    return {<br>      school: school.school,<br>      degree: school.degree,<br>      fieldOfStudy: school.fieldOfStudy,<br>      startedAt: school.studiedFrom_ISO8601,<br>      endedAt: school.studiedTill_ISO8601,<br>    };<br>  }),<br>  workHistory: parsedCV.workHistory?.map(work =&gt; {<br>    // ...<br>  }),<br>};<br><br>return mappedCV;</pre><h4>Update the candidate data</h4><p>Now that we have a JSON with structured data extracted from the CV, we can send the data back to the ATS to update the candidate’s data using the <a href="https://superface.ai/recruitment/update-candidate">Update Candidate</a> use case:</p><pre>exports.updateCandidate = async (sdk, providerOptions, candidate) =&gt; {<br>  const profile = await sdk.getProfile(&#39;recruitment/update-candidate@1.0.0&#39;);<br><br>  const result = await profile<br>    .getUseCase(&#39;UpdateCandidate&#39;)<br>    .perform(candidate, providerOptions);<br><br>  result.unwrap();<br><br>  return true;<br>};</pre><h4>Using another ATS?</h4><p>If you take a look at the code, there aren’t any mentions of Workable, Cloudmersive or OpenAI. That’s because the use cases are designed in provider-neutral way. In case of ATS, we use a <a href="https://superface.ai/blog/integrating-any-applicant-tracking-system">unified terminology</a>, so if you need to use another ATS, you don’t need to rewrite the whole application. Instead, you can change atsProviderOptions in <a href="https://github.com/superfaceai/cv-analyzer/blob/main/src/index.js">src/index.js</a> file:</p><pre>// Options for Workable<br>const atsProviderOptions = {<br>  provider: &#39;workable&#39;,<br>  parameters: {<br>    SUBDOMAIN: process.env.WORKABLE_SUBDOMAIN,<br>  },<br>  security: {<br>    bearer_token: {<br>      token: process.env.WORKABLE_TOKEN,<br>    },<br>  },<br>};</pre><p>And if you’d like to use, for example, Breezy HR, set atsProviderOptions like this:</p><pre>// Options for Breezy HR<br>const atsProviderOptions = {<br>  provider: &#39;breezy-hr&#39;,<br>  parameters: {<br>    COMPANY_ID: process.env.BREEZY_HR_COMPANY_ID,<br>    ACCESS_TOKEN: process.env.BREEZY_HR_ACCESS_TOKEN,<br>  },<br>};</pre><h3>Next steps</h3><p>In this demo application we’ve used 6 different API use cases from 3 different API providers, without ever looking at the API docs. That’s the advantage of Superface.</p><p>Do you need to integrate Applicant Tracking Systems like Workable, Lever, or SAP SuccessFactors? Check out our <a href="https://superface.ai/domain/ats">Applicant Tracking Systems integrations</a>. And don’t miss other integrations in the <a href="https://superface.ai/catalog">Superface catalog</a>.</p><p><em>Originally published at </em><a href="https://superface.ai/blog/cv-analyzer"><em>https://superface.ai</em></a><em> on January 20, 2023.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b0d5fd7d716" width="1" height="1" alt=""><hr><p><a href="https://medium.com/superface/turn-cv-to-structured-data-with-gpt-3-and-node-js-b0d5fd7d716">Turn CV to structured data with GPT-3 and Node.js</a> was originally published in <a href="https://medium.com/superface">Superface</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Power-up your OpenAPI Spec in 13 steps]]></title>
            <link>https://medium.com/superface/power-up-your-openapi-spec-in-13-steps-df84e4e8fc26?source=rss----a27729ffd476---4</link>
            <guid isPermaLink="false">https://medium.com/p/df84e4e8fc26</guid>
            <category><![CDATA[sdk-generation]]></category>
            <category><![CDATA[api-development]]></category>
            <category><![CDATA[openapi-specification]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Jakub Vacek]]></dc:creator>
            <pubDate>Thu, 29 Sep 2022 15:22:14 GMT</pubDate>
            <atom:updated>2022-09-29T15:22:14.062Z</atom:updated>
            <content:encoded><![CDATA[<h4>API specifications are not just for documenting APIs, you can use them for testing and SDK generation — but you need to write them right</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mBrFI8RdRpyqPRC3EU4ciw.png" /></figure><p>During my work on <a href="https://superface.ai/blog/integration-designer-announcement">Superface Integration Designer</a>, I used numerous OpenAPI Specification (OAS) files describing the APIs of some well known service providers. The quality of these specifications varies heavily, and if you decide to use them as input for some tool, you can end up with poor results. The poor quality of OAS files was frustrating for me, so I decided to write down the most common issues I ran into. The list is primarily focused on OpenAPI Specification, but most of the suggestions are applicable to other specification formats, and also touch upon API design.</p><p>Let’s assume that you write an API specification. Why should you think about automated processing of your API specification? Because you will benefit from it in the long run. There is <a href="https://openapi.tools/">a growing number of tools that use OpenAPI Specification</a> as input, and allow you to do things like validation, SDK code generation, API mocking, automated security checks, and more. If you build APIs, take a look at them. It could change the way you look at the role of API specification in your development process.</p><p>There is a common misconception that people create API specification for other people to read. Specification writers can then take shortcuts. Shortcuts lead to lower quality of API specification which, in the end, results in subpar output of tools processing your API specification.</p><p>Let’s look at the most common errors that complicate OAS documents use.</p><h3>Play safe with versions</h3><p>Use well established versions of OpenAPI Specification which are supported by automated processing tools. By using an established OAS version, you give your users a larger variety of tools compatible with your specification.</p><p>As of September 2022, the majority of tools supports OAS version 3.0, but not every tool supports OAS 3.1 or 2.0. When in doubt, check the <a href="https://openapi.tools/">list of tools</a>.</p><h3>Keep your API simple</h3><p>This one is more connected to API design, but I consider this significant enough to be mentioned. When designing your API, keep in mind that you need to be able to describe it with OAS. So think twice before using non-standard security schemes or obscure request/response types.</p><p>For example, in one of the OAS documents we tested an endpoint that accepted either a string or an object with properties, and returned the same type based on the request contents. This kind of relationship between the request and the response is not possible to describe in OpenAPI Specification. The tool processing this specification has no way to connect the request schema with the appropriate response schema.</p><h3>Describe everything, but keep it short</h3><p>OAS document doesn’t replace documentation, but complements it. It’s a reference where each entity should be sufficiently documented, but shouldn’t contain marketing language or information that isn’t directly needed to use the API. Tutorials, guides, and use cases belong to dedicated documents.</p><h3>Provide a sandbox server</h3><p>In the OpenAPI Specification, servers represents an array of objects with information on how to connect to different instances of the API. These can be, for example, production and staging servers. If all endpoints in your API require authorization, provide a sandbox service which operates on dummy data. This allows a user to quickly try out your API in their project.</p><h3>Specify security</h3><p>Define all security schemes and connect each endpoint to the correct scheme. Every scheme should describe how to obtain the key or authorize (or link to the documentation). Many OAS documents define multiple global security schemes, but don’t specify which endpoint uses which security scheme.</p><h3>Keep the naming consistent</h3><p>Use names that are descriptive and clear, avoid mixing different naming conventions (like camelCase, snake_case, and kebab-case). Avoid property names or enums starting with non-alphabetic characters (like numbers or dashes) as these can lead to issues during automated processing.</p><pre>schema:<br>  type: object<br>  <em># DO NOT DO THIS:</em><br>  properties:<br>    accountName:<br>      type: string<br>    account_id:<br>      type: string<br>    account-description:<br>      type: string<br>    3h:<br>      type: number<br>    sort:<br>      type: string<br>      enum:<br>        - -start_at<br>        - +start_at</pre><h3>Enumerate all property types</h3><p>When it comes to defining the data schema and property types, be as precise as possible. Don’t forget to cover whether an endpoint accepts multiple types, for example string and null. This information is crucial for the quality of the generated output. This is the most common problem I have encountered. When you generate an SDK from such an incorrectly described OAS document, the client code doesn&#39;t expect the value to be nullable, which will cause errors.</p><pre>schema:<br>  type: object<br>  properties:<br>    foo:<br>      <em># Works in OAS 3.1</em><br>      <em># foo can be string or null</em><br>      type: [&#39;string&#39;, &#39;null&#39;]<br>    bar:<br>      <em># Works in OAS 3.0</em><br>      <em># bar can be string or null</em><br>      type: string<br>      nullable: <strong>true</strong></pre><h3>Mark required properties</h3><p>Make sure to correctly mark required properties. Ignoring the required property is another common mistake which affects validation and mocking tools.</p><pre>schema:<br>  type: object<br>  properties:<br>    foo:<br>      type: string<br>    <em># bar can be undefined</em><br>    bar:<br>      type: string<br>  required: [&#39;foo&#39;]</pre><h3>Don’t forget errors</h3><p>List all the error responses with correct status codes and response bodies, provide example errors, follow HTTP status code definitions. OpenAPI Specification allows multiple ways to define error response. You can use the default response, or wildcard response 4xx as described in the <a href="https://swagger.io/specification/#responses-object">Specification</a>. Error responses are vital when you are using the specification with a tool for mocking responses.</p><h3>Add examples</h3><p>You should provide a valid example for each parameter. These examples are useful for API mocking and SDK generation tools, as they can be used as mock values.</p><pre>schema:<br>  type: object<br>  properties:<br>    temp:<br>      type: number<br>      description: &#39;Temperature in kelvin&#39;<br>      example: 293.25 <em># &lt;-- example value</em><br>    description:<br>      type: string<br>      description: &#39;Weather condition within the group&#39;<br>      example: &#39;broken clouds&#39; <em># &lt;-- example value</em><br>    country:<br>      type: string<br>      description: &#39;Country code (GB, JP etc.)&#39;<br>      examples:<br>        - AU <em># &lt;-- first example value</em><br>        - CZ <em># &lt;-- second example value</em></pre><h3>Define default values</h3><p>For optional properties, make sure to specify a default value if there is one. Similar to examples, this is useful for tools and documentation purposes.</p><pre>schema:<br>  type: string<br>  enum: [json, xml, html]<br>  default: &#39;json&#39; <em># &lt;-- default value</em></pre><h3>Detail property format</h3><p>In addition to type, you can also specify the format of the value, for example int32, date-time and password. You can also specify a regular expression. The full list of possible values can be found in the <a href="https://json-schema.org/understanding-json-schema/reference/generic.html">JSON schema specification</a>. This is useful both for validation and mocking tools.</p><pre>id:<br>  type: integer<br>  description: City ID<br>  format: int32 <em># &lt;--</em><br>  example: 2172797</pre><h3>Use a linter</h3><p>You can automate most of these checks by using an OpenAPI Specification linter. There are many linters out there, although most of them just validate OAS documents with a prepared JSON Schema. Our <a href="https://github.com/superfaceai/openapi-linter">OpenAPI Linter</a> takes a different approach, it uses the Spectral linter with a custom set of rules. These rules were designed to validate OAS documents intended for use with automatic processing tools.</p><p>In the list above, I highlighted parts of the specifications that are often neglected, but play an important role in automatic processing tools. Focus on these parts, so your specification is useful both for users and automatic processing tools. With a well-written API specification, users can automatically generate client code for your API, mock an entire server, and much more. These possibilities can give you a head start on your competitors. So remember, treat your OpenAPI Specification as code, not just as a structured document for humans.</p><h3>Resources</h3><p>Here is a list of articles that can be helpful when working on API specification:</p><ul><li><a href="https://spec.openapis.org/oas/latest.html">Specification of OpenAPI Specification</a></li><li><a href="https://json-schema.org/specification.html">JSON Schema Specification</a></li></ul><p>Articles about design-first vs. code-first approach:</p><ul><li><a href="https://blog.stoplight.io/api-first-api-design-first-or-code-first-which-should-you-choose">Stoplight: Design first</a></li><li><a href="https://apisyouwonthate.com/blog/api-design-first-vs-code-first">APIs You Won’t Hate: Design First</a></li><li><a href="https://swagger.io/blog/api-design/design-first-or-code-first-api-development/">Swagger: Design First</a></li></ul><p><em>Originally published at </em><a href="https://superface.ai/blog/power-up-openapi-spec"><em>https://superface.ai</em></a><em> on September 29, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=df84e4e8fc26" width="1" height="1" alt=""><hr><p><a href="https://medium.com/superface/power-up-your-openapi-spec-in-13-steps-df84e4e8fc26">Power-up your OpenAPI Spec in 13 steps</a> was originally published in <a href="https://medium.com/superface">Superface</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Instagram API: Find the right account ID]]></title>
            <link>https://medium.com/superface/instagram-api-find-the-right-account-id-1ec63953de5a?source=rss----a27729ffd476---4</link>
            <guid isPermaLink="false">https://medium.com/p/1ec63953de5a</guid>
            <category><![CDATA[api-integration]]></category>
            <category><![CDATA[instagram-api]]></category>
            <category><![CDATA[facebook-api]]></category>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Jan Vlnas]]></dc:creator>
            <pubDate>Wed, 28 Sep 2022 21:34:50 GMT</pubDate>
            <atom:updated>2022-09-28T21:44:20.706Z</atom:updated>
            <content:encoded><![CDATA[<h4>How to get account details from Instagram Graph API</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*gwQ4iJEbMWm2bSLR.jpg" /><figcaption>Photo by <a href="https://unsplash.com/@solenfeyissa?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Solen Feyissa on Unsplash</a></figcaption></figure><p>To manage your Instagram account through an API, you need two things: a user access token and a business account ID. Getting an access token is easy, but figuring out the account ID takes a few steps and sometimes causes a confusion.</p><p><strong>Prerequisites:</strong> This tutorial assumes you have an Instagram business account connected with a Facebook page and Facebook application with Instagram Graph API enabled. Check my previous article on <a href="https://medium.com/superface/get-started-with-instagram-api-the-setup-9d1a82db55e">how to set up a test account for Instagram API</a>.</p><p><a href="https://medium.com/superface/get-started-with-instagram-api-the-setup-9d1a82db55e">Get started with Instagram API: The Setup</a></p><p>If you are currently troubleshooting requests to Instagram’s API and can’t wrap your head around their IDs, skip right away to <a href="#d08f">common ID confusions</a>.</p><h3>Get an access token</h3><p>For the following steps, I will use <a href="https://developers.facebook.com/tools/explorer/">Graph API Explorer</a>. This is a useful tool for trying out Facebook’s APIs and also to obtain access tokens for authorized API access.</p><p>In the right sidebar, select the previously created application under “Meta App”. Make sure “User Token” is selected and add the following permissions: instagram_basic, pages_show_list, and instagram_content_publish (this will come handy in later tutorials).</p><figure><img alt="Detail of Graph API Explorer sidebar with selected Meta App, User Token, and required permissions" src="https://cdn-images-1.medium.com/max/578/0*89gesv1L9C5oNmsU.png" /></figure><p>Finally, click “Generate Access Token”. Facebook will display a pop-up with prompts to authorize access to your Instagram and Facebook pages. Make sure to select <strong>both</strong> your testing Instagram account and the associated Facebook page.</p><figure><img alt="Facebook authorization dialog with Instagram account selected" src="https://cdn-images-1.medium.com/max/880/0*ZQm9CcH0eESaw-R5.png" /></figure><h3>Find your Instagram account ID</h3><p>If you authorized the application correctly, you should be able to list Facebook pages the application has access to.</p><p>Enter the following path to the Graph API Explorer: me/accounts. After submitting, you should see Facebook pages you gave your application access to.</p><figure><img alt="Graph API Explorer with path set to me/accounts and authorized page in response, page’s ID is highlighted." src="https://cdn-images-1.medium.com/max/880/0*tqpjuwPVP3UmP1SM.png" /></figure><p>Now, copy the value id of your page and enter the following path:</p><pre>&lt;page ID&gt;?fields=instagram_business_account</pre><p>In the response, you will see both the Facebook’s page ID and the ID of your Instagram account. Copy the value of id under instagram_business_account — this ID is necessary for further interactions with your Instagram account via API.</p><figure><img alt="Graph API Explorer with path set to Facebook page ID and fields set to instagram_business_account. In response, there is a nested field “id” under instagram_business_account object." src="https://cdn-images-1.medium.com/max/880/0*c5MQs4__7qcFkhdG.png" /></figure><h3>Get account details</h3><p>With this ID, we can retrieve basic information about our Instagram account, like its username, name, and profile picture. Try querying the following path with your Instagram business account ID:</p><pre>&lt;business account ID&gt;?fields=id,name,username,profile_picture_url</pre><figure><img alt="Graph API Explorer with Instagram account details" src="https://cdn-images-1.medium.com/max/880/0*bET7sReclOgQ5IFk.png" /></figure><h3>All in single request</h3><p>There is also an undocumented way to retrieve Instagram account details in a single request from me/accounts. This way, we can skip intermediary requests and retrieve authorized Instagram accounts directly:</p><pre>me/accounts?fields=instagram_business_account{id,name,username,profile_picture_url}</pre><figure><img alt="Graph API Explorer with Instagram account details retrieved from me/accounts edge" src="https://cdn-images-1.medium.com/max/880/0*FLSM1LbvrDT8zVMj.png" /></figure><p>In Facebook’s Graph API, it is possible to traverse some edges within a single request — this is what the curly braces in the fields query parameter are for. In other words, we are telling the API, “give me these fields for instagram_business_account edge under me/accounts edge”.</p><h3>Common ID confusions</h3><p>A common source of mistakes when dealing with Graph API is use of an incorrect type ID. If the API doesn’t behave like you expect, check if you have the right ID. In case of Instagram Graph API, we are dealing with the following IDs:</p><ul><li>Facebook Page ID — retrieved from me/accounts endpoint identifies <a href="https://developers.facebook.com/docs/instagram-api/reference/page">Page node</a> and acts as an entry point to get an Instagram account associated with the Page.</li><li>Instagram (Business) Account ID — retrieved from Page node under instagram_business_account edge. Documentation refers to it as <a href="https://developers.facebook.com/docs/instagram-api/reference/ig-user">IG User node</a>. It must be accessed with <em>a user</em> access token.</li><li>ig_id or Instagram User ID — this is an ID of the Instagram account from the legacy, deprecated API. It is intended for migration of applications using the pre-graph API, but it&#39;s not used anywhere else. It&#39;s also represented as a number, while Graph API IDs are strings.</li></ul><h3>Get Instagram account easier way</h3><p>Picking a correct Instagram account is a pretty basic integration task, so we’ve built an easier way to do that. If you use Node.js, before you grab fetch and start building your custom abstraction, try OneSDK. We have an integration ready to <a href="https://superface.ai/social-media/publishing-profiles?provider=instagram">get a list of authorized Instagram accounts</a>. And the same interface works also for Facebook, LinkedIn, Pinterest, and Twitter - but let&#39;s keep it for another time.</p><p>First, install OneSDK into your project:</p><pre>npm i @superfaceai/one-sdk</pre><p>And paste the following code into profiles.js file:</p><pre>const { SuperfaceClient } = require(&#39;@superfaceai/one-sdk&#39;);<br><br>// Replace the value with the token from Graph Explorer<br>const ACCESS_TOKEN = &#39;YOUR USER ACCESS TOKEN HERE&#39;<br><br>const sdk = new SuperfaceClient();<br><br>async function getProfiles() {<br>  const sdkProfile = await sdk.getProfile(&#39;social-media/publishing-profiles@1.0.1&#39;);<br>  const result = await sdkProfile<br>    .getUseCase(&#39;GetProfilesForPublishing&#39;)<br>    .perform({}, {<br>      provider: &#39;instagram&#39;,<br>      parameters: {<br>        accessToken: ACCESS_TOKEN<br>      }<br>    });<br><br>  try {<br>    return result.unwrap();<br>  } catch (error) {<br>    console.error(error);<br>  }<br>}<br><br>getProfiles().then((result) =&gt; {<br>  console.log(result.profiles);<br>});</pre><p>Don’t forget to insert your actual user access token as a value of the ACCESS_TOKEN variable. You can copy it from Graph API Explorer:</p><figure><img alt="Graph API Explorer right sidebar with button “Copy to clipboard” next to the access token highlighted" src="https://cdn-images-1.medium.com/max/644/0*c_5G7AmB8srYGUVs.png" /></figure><p>When you run this code, you will get an array with authorized accounts, their ID, username, and profile image:</p><pre>$ node profiles.js<br>[<br>  {<br>    id: &#39;17841455280630860&#39;,<br>    name: &#39;Dev Testing App IG Acct&#39;,<br>    username: &#39;dev_testing_app&#39;,<br>    imageUrl: &#39;https://scontent.fprg5-1.fna.fbcdn.net/...&#39;<br>  }<br>]</pre><p>The code behind the integration is <a href="https://github.com/superfaceai/station/tree/aee145aae8626f8736d8b8bda55cc77187b9f852/grid/social-media/publishing-profiles/maps">open-source</a> and your application communicates with Instagram API directly without intermediary servers.</p><h3>Conclusion</h3><p>With the Instagram account ID, we can start managing the account via API. In the following articles I will cover publishing of images and videos, authorization flow, and retrieving posts and comments. If you don’t want to miss it, <a href="https://medium.com/superface">follow Superface on Medium</a>.</p><p><a href="https://medium.com/superface">Superface</a></p><p>Was this tutorial useful or did you run into any problems? Let me know in the comments!</p><p><em>Originally published at </em><a href="https://superface.ai/blog/instagram-account-id"><em>https://superface.ai</em></a><em> on September 26, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1ec63953de5a" width="1" height="1" alt=""><hr><p><a href="https://medium.com/superface/instagram-api-find-the-right-account-id-1ec63953de5a">Instagram API: Find the right account ID</a> was originally published in <a href="https://medium.com/superface">Superface</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Get started with Instagram API: The Setup]]></title>
            <link>https://medium.com/superface/get-started-with-instagram-api-the-setup-9d1a82db55e?source=rss----a27729ffd476---4</link>
            <guid isPermaLink="false">https://medium.com/p/9d1a82db55e</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[instagram-api]]></category>
            <category><![CDATA[social-media-management]]></category>
            <category><![CDATA[facebook-api]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Jan Vlnas]]></dc:creator>
            <pubDate>Wed, 28 Sep 2022 21:18:47 GMT</pubDate>
            <atom:updated>2022-09-28T21:43:37.416Z</atom:updated>
            <content:encoded><![CDATA[<h4>How to create a business account and a Facebook app</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*74kG65vYQy3Ga4tN.jpg" /><figcaption>Photo by <a href="https://unsplash.com/@solenfeyissa?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Solen Feyissa on Unsplash</a></figcaption></figure><p>Instagram Graph API is Facebook’s official way to access Instagram from your application. The API allows you to manage your account, publish content, and access some public data from Instagram, but only a subset of features is available compared to Instagram’s official applications.</p><p>That’s no coincidence. Facebook severely <a href="https://about.fb.com/news/2018/04/restricting-data-access/">restricted its APIs</a> after the Cambridge Analytica scandal. Instagram Graph API was designed with these privacy concerns in mind, <a href="https://developers.facebook.com/blog/post/2020/03/10/final-reminder-Instagram-legacy-api-platform-disabled-mar-31/">replacing former Instagram API</a> which was much more open.</p><p>Some design decisions and limitations around Instagram Graph API are so confusing, developers often ask how to perform even basic tasks. For example, how to get access to the API for their account, or figure out the correct account ID. I’ve answered numerous questions like this, which led me to start this series.</p><p>This is a first dive into Instagram Graph API, covering the initial prerequisites: creating an Instagram business account and setting up a Facebook app. In the next article I will cover how to get an access token and basic information about Instagram account, including the business account ID required for further interactions. In future posts, I will cover authorization in Node.js, content publishing, and retrieval of posts and comments.</p><h3>Pair Instagram account with Facebook Page</h3><p>Instagram Graph API can be used only by “<a href="https://help.instagram.com/138925576505882">Instagram Professional accounts</a>” — this includes Business accounts (intended for companies), and Creator accounts (intended for individuals, like influencers). The good news is you don’t need to pay anything for a Professional account.</p><p>Before you proceed, you need three things:</p><ul><li>A Facebook account (can be your personal)</li><li>A Facebook page — ideally a dedicated testing page, so <a href="https://www.facebook.com/pages/create/">create one now</a></li><li>An Instagram account — ideally a dedicated account for testing (<a href="https://www.instagram.com/accounts/emailsignup/">sign up for one</a>)</li></ul><p>For development purposes, we will need to turn the <a href="https://help.instagram.com/502981923235522">Instagram account into a Business account</a> and pair it with the Facebook page.</p><p>Once you log into your Instagram account, go to account settings. Here, click “Switch to professional account”.</p><figure><img alt="Instagram account settings with “Switch to professional account” under the left menu" src="https://cdn-images-1.medium.com/max/880/0*i9w4Qfpxa6hO67n2.png" /></figure><p>You have two options: Creator and Business. Select Business, pick a category (can be anything) and skip the step to add contact information.</p><figure><img alt="Selection of Professional account type with Business selected" src="https://cdn-images-1.medium.com/max/880/0*ORP9_8heIc5WLNWu.png" /></figure><p>Next, on the Facebook side, go to your Facebook page’s settings. On “Professional dashboard” select “Linked Accounts” and you should see a button to “Connect account” from Instagram.</p><figure><img alt="Dashboard with Facebook page settings with Linked Accounts highlighted in left-side navigation" src="https://cdn-images-1.medium.com/max/880/0*J-AMgyop2orqeyCC.png" /></figure><figure><img alt="Linked account page with Connect account highlighted" src="https://cdn-images-1.medium.com/max/880/0*iWVLKZsHIhzJmwQo.png" /></figure><p>This will show you a pop-up to enter Instagram credentials, and once you log in, you should see a success message.</p><figure><img alt="Success message: Instagram connected" src="https://cdn-images-1.medium.com/max/880/0*PwARRwaHNnNlCAMA.png" /></figure><h3>Create a Facebook application</h3><p>Next, we will need to create a Facebook app. Visit <a href="https://developers.facebook.com/apps/">My apps</a> on Facebook (Meta) for Developers site and click “Create App”. This will take you to app type selection.</p><figure><img alt="App type selection with the first option, Business, selected" src="https://cdn-images-1.medium.com/max/880/0*sCR8e4EbsXhjx-af.png" /></figure><p>Select “Business”, enter name and contact e-mail, and finally, you should see various products to add to your app. Find Instagram Graph API, click “Set up”, and that’s it for now.</p><figure><img alt="Add products to app screen with Instagram Graph API highlighted" src="https://cdn-images-1.medium.com/max/880/0*EbXBbfb_4Woekk9U.png" /></figure><h3>Next steps</h3><p>In the <a href="https://medium.com/superface/instagram-api-find-the-right-account-id-1ec63953de5a">next article</a>, we will get to work with the API itself.</p><p><a href="https://medium.com/superface/instagram-api-find-the-right-account-id-1ec63953de5a">Instagram API: Find the right account ID</a></p><p>If you don’t want to miss future tutorials, <a href="https://medium.com/superface">follow Superface on Medium</a>.</p><p><a href="https://medium.com/superface">Superface</a></p><p>Let me know if this post is useful to you or if you encounter any problems with my instructions — just comment on the story.</p><h3>Resources</h3><p>Facebook is constantly changing their products, so it’s possible that by the time you read this article, some flows are entirely different. You can refer to the following official resources, although in some cases these may also be outdated.</p><ul><li><a href="https://help.instagram.com/502981923235522/">Set Up a Business Account on Instagram</a></li><li><a href="https://help.instagram.com/570895513091465/">Add or Change the Facebook Page Connected to Your Instagram Business Account</a> — as of September 2022 this guide seems to be outdated; it describes the possibility to connect a Facebook page from Instagram side, but I didn’t find the described functionality in Instagram’s web interface.</li><li><a href="https://developers.facebook.com/docs/instagram-api/getting-started">Instagram Graph API: Getting Started</a></li></ul><p><em>Originally published at </em><a href="https://superface.ai/blog/instagram-setup"><em>https://superface.ai</em></a><em> on September 23, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9d1a82db55e" width="1" height="1" alt=""><hr><p><a href="https://medium.com/superface/get-started-with-instagram-api-the-setup-9d1a82db55e">Get started with Instagram API: The Setup</a> was originally published in <a href="https://medium.com/superface">Superface</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[API is like a box of chocolates, you never know what you GET]]></title>
            <link>https://medium.com/superface/api-is-like-a-box-of-chocolates-you-never-know-what-you-get-7632a9406239?source=rss----a27729ffd476---4</link>
            <guid isPermaLink="false">https://medium.com/p/7632a9406239</guid>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[api-integration]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Jan Vlnas]]></dc:creator>
            <pubDate>Mon, 19 Sep 2022 06:42:36 GMT</pubDate>
            <atom:updated>2022-09-19T06:42:36.180Z</atom:updated>
            <cc:license>http://creativecommons.org/licenses/by/4.0/</cc:license>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*9ayJB5mIvlgegigu.jpg" /><figcaption>Credit: <a href="https://www.pexels.com/photo/chocolate-cake-box-352876/">Lukas on Pexels</a></figcaption></figure><p>Imagine you get a task to integrate an API. It’s a partner API, the code is outside your control, and it’s not very widely used. But there is at least some documentation. You quickly dive in. There’s a list of endpoints, required parameters, authorization, but something’s missing. There is absolutely no information about API responses, not even how a regular response should look like, not to mention possible errors. So, it’s time to pull out an HTTP client, and start poking the API with requests to see how it behaves.</p><p>Dealing with undocumented responses isn’t such a big deal, we have tools for visualizing JSON (for example <a href="https://jsoncrack.com/">JSON Crack</a>) and inferring its schema (like <a href="https://jvilk.com/MakeTypes/">MakeTypes</a>). It’s those edge cases which completely throw off any assumptions you already made.</p><p>Recently, I worked with an API which was like that. The documentation only mentioned that endpoints exist, and some particular parameters are required. Once I figured API’s weird, custom-made authorization schema, I started to poke around the endpoints.</p><p>First thing I noticed was responses’ content type. While the API responds with JSON, the content-type header marks the response as HTML. This breaks automatic parsing in most HTTP clients (and also syntax highlighting and formatting), but the response can still be parsed manually. The fun started when some responses included HTML warnings with the data, for example:</p><pre>&lt;br /&gt;<br>&lt;b&gt;Warning&lt;/b&gt;: Undefined array key &quot;TEST&quot; in &lt;b&gt;/some/source/file&lt;/b&gt; on line<br>&lt;b&gt;123&lt;/b&gt;<br>&lt;br /&gt;<br>&lt;br /&gt;<br>{&quot;foo&quot;:&quot;bar&quot;}</pre><p><em>Technically,</em> the API behaved consistently: it claimed to respond with HTML, and so it did. But in practice, this behavior renders the API mostly useless for consumers. Sure, I could search the response and parse only the JSON part. While finding clever hacks is fun, it’s usually not sustainable in the long run. Not to mention that keeping error messages exposing your source files structure is a <a href="https://owasp.org/www-community/attacks/Full_Path_Disclosure">security risk</a>. I reported the issue to the API provider (somehow surprised no one reported this issue before). They were swift to respond and improved their API based on my suggestions.</p><p>While I love to solve technical challenges as any other developer, sometimes it’s really easier to talk to people. However, it frustrates me to think how much time is wasted by examining on poorly documented APIs with surprising behaviors. And while we should be advocating for better developer experience even for internal and partner APIs, we can also share our discoveries by abstracting APIs into <a href="https://superface.ai/blog/api-plumbing">reusable use cases</a>.</p><p>Now to you: <strong>What was the weirdest API behavior you dealt with?</strong></p><p><em>Originally published at </em><a href="https://superface.ai/blog/box-of-chocolates"><em>https://superface.ai</em></a><em> on September 16, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7632a9406239" width="1" height="1" alt=""><hr><p><a href="https://medium.com/superface/api-is-like-a-box-of-chocolates-you-never-know-what-you-get-7632a9406239">API is like a box of chocolates, you never know what you GET</a> was originally published in <a href="https://medium.com/superface">Superface</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[‘Look ma, no config file!’ Introducing OneSDK 2.0]]></title>
            <link>https://medium.com/superface/look-ma-no-config-file-introducing-onesdk-2-0-dc0574b527c7?source=rss----a27729ffd476---4</link>
            <guid isPermaLink="false">https://medium.com/p/dc0574b527c7</guid>
            <category><![CDATA[api]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[release-notes]]></category>
            <category><![CDATA[nodejs]]></category>
            <dc:creator><![CDATA[Jan Vlnas]]></dc:creator>
            <pubDate>Tue, 16 Aug 2022 13:41:29 GMT</pubDate>
            <atom:updated>2022-08-16T13:41:29.328Z</atom:updated>
            <content:encoded><![CDATA[<h4>Easier, leaner, and smarter. OneSDK v2.0.0 simplifies the usage of Superface integrations and reduces the memory footprint.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*5uMZqzMNpJiK3je2.png" /></figure><p><a href="https://github.com/superfaceai/one-sdk-js">OneSDK</a> is a universal client for consuming API integrations. It is a core component of the Superface ecosystem — whether you pick an <a href="https://superface.ai/catalog">existing integration</a>, or decide to build one yourself.</p><p>Today, we are excited to announce OneSDK v2.0.0, a new major version which simplifies the usage of Superface integrations and reduces the memory footprint. If you are using OneSDK in your application, pay attention to the <a href="https://superface.ai/blog/one-sdk-2.0#breaking-changes">breaking changes</a> and check out the <a href="https://superface.ai/docs/upgrade/one-sdk-v2">upgrade guide</a>. But first, let’s dive into the new features.</p><h3>Use OneSDK without configuration</h3><p>The most significant change in this release is simplified use of integrations published in the <a href="https://superface.ai/catalog">Superface registry</a>. Previously, you had to use the Superface CLI (@superfaceai/cli package) to install the integration profile and configure providers. This updated the super.json configuration file and saved .supr files into local project.</p><p>With OneSDK v2, these steps are not required anymore. To start using Superface integrations, pick one from the <a href="https://superface.ai/catalog">catalog</a>, install the @superfaceai/one-sdk package, and use the provided example code.</p><p>As an example, let’s display a <a href="https://superface.ai/weather/forecast-city">weather forecast</a> with my favorite weather service, <a href="https://wttr.in/">wttr.in</a>.</p><p>First, install OneSDK with npm:</p><pre>npm i @superfaceai/one-sdk</pre><p>And paste the following code into a weather.js file:</p><pre>const { SuperfaceClient } = require(&#39;@superfaceai/one-sdk&#39;);</pre><pre>// Change to your city!<br>const city = &#39;New York City, NY, USA&#39;;</pre><pre>const sdk = new SuperfaceClient();</pre><pre>async function showWeather() {<br>  const profile = await sdk.getProfile(&#39;weather/forecast-city@1.0.0&#39;);<br>  const result = await profile.getUseCase(&#39;GetWeatherForecastInCity&#39;).perform(<br>    {<br>      city,<br>    },<br>    {<br>      provider: &#39;wttr-in&#39;,<br>    }<br>  );</pre><pre>console.log(result.unwrap());<br>}</pre><pre>showWeather();</pre><p>When you run node weather.js, you should get a temperature forecast for the next three days:</p><pre>[<br>  {<br>    averageTemperature: 28,<br>    date: &#39;2022-08-11&#39;,<br>    maxTemperature: 34,<br>    minTemperature: 23,<br>  },<br>  {<br>    averageTemperature: 26,<br>    date: &#39;2022-08-12&#39;,<br>    maxTemperature: 30,<br>    minTemperature: 22,<br>  },<br>  {<br>    averageTemperature: 25,<br>    date: &#39;2022-08-13&#39;,<br>    maxTemperature: 31,<br>    minTemperature: 20,<br>  },<br>];</pre><p>OneSDK v2 will fetch and cache profiles at runtime, which means super.json configuration is no longer necessary. If you already use OneSDK with super.json, you don&#39;t need to change anything. The super.json file acts as a central place for locking profile versions and decoupling providers configuration from the code. It is also needed for using local profiles and maps (see <a href="#fd17">breaking changes</a> below).</p><h3>Pass security values at runtime</h3><p>While OneSDK doesn’t need a configuration file, many providers require an API token or another form of authentication. Previously, we used <a href="https://superface.ai/blog/changelog-november-2021#provider-integration-parameters">integration parameters</a> for passing provider-specific values at runtime, such as OAuth access tokens. Now you can also use security values in the perform method. Pass in a security option with required security values; here is an example for sending an email with SendGrid:</p><pre>const profile = await sdk.getProfile(&#39;communication/send-email@2.1.0&#39;);</pre><pre>// Use the profile<br>const result = await profile.getUseCase(&#39;SendEmail&#39;).perform(<br>  {<br>    from: &#39;<a href="/service/mailto:no-reply@example.com">no-reply@example.com</a>&#39;,<br>    to: &#39;<a href="/service/mailto:jane.doe@example.com">jane.doe@example.com</a>&#39;,<br>    subject: &#39;Your order has been shipped!&#39;,<br>    text: &#39;Hello Jane, your recent order on Our Shop has been shipped.&#39;,<br>  },<br>  {<br>    provider: &#39;sendgrid&#39;,<br>    security: {<br>      bearer_token: {<br>        token: &#39;&lt;your token from sendgrid&gt;&#39;,<br>      },<br>    },<br>  }<br>);</pre><p>The property name (bearer_token in this example) of the security value is provider-specific. The code examples in the catalog will help you figure out what values need to be passed in.</p><h3>Fewer dependencies, less memory usage</h3><p>We want OneSDK to be usable everywhere you can run Node.js, regardless of resource constraints. Previous versions required a Comlink parser, which in turn depended on the TypeScript package at runtime. In OneSDK v2, we have removed the parser, resulting in a leaner package with a smaller memory footprint.</p><figure><img alt="Screenshot of two memory usage charts. First shows OneSDK 1.5.2 using 61 MB of heap, the second shows OneSDK 2.0.0 using 31 MB of heap." src="https://cdn-images-1.medium.com/max/1024/1*wHOtFJoRoqpRGZLakG28xQ.png" /><figcaption>With a single profile and a single map, OneSDK v2.0.0 consumes 30 MB less memory than OneSDK v1.5.2 (<a href="https://github.com/jnv/one-sdk-benchmark">benchmark code</a>)</figcaption></figure><p>Since the parser is no longer included in OneSDK, local maps and profiles need to be compiled with Superface CLI. <a href="#fd17">Read below</a> about this breaking change.</p><h3>Breaking changes</h3><p>Change in a major version implies breaking changes, which is also the case for OneSDK v2. The most significant breaking change is the removal of the Comlink parser, which affects OneSDK users with local profile and map files.</p><p>We have also changed the default cache location and reduced the usage of the superface/ directory. These changes (hopefully) won&#39;t break your application, but can help you clean up the previously generated files in your project.</p><h3>Local profiles and maps require a compile step</h3><p>If your project depends on local profiles or maps, OneSDK v2 won’t automatically parse them anymore, and throws an error during initialization. To see if you are affected, check the superface/super.json for &quot;file&quot; properties, for example, the following configuration depends on a local profile (my-profile.supr) and a map (my-profile.my-provider.suma):</p><pre>{<br>  &quot;profiles&quot;: {<br>    &quot;my-profile&quot;: {<br>      &quot;file&quot;: &quot;./my-profile.supr&quot;,<br>      &quot;providers&quot;: {<br>        &quot;my-provider&quot;: {<br>          &quot;file&quot;: &quot;./my-profile.my-provider.suma&quot;<br>        }<br>      }<br>    }<br>  }<br>}</pre><p>OneSDK will look for compiled *.ast.json files to load them at runtime. Run npx @superfaceai/cli@latest compile in your project to compile the source profiles and maps. We recommend adding a compilation step to your existing build step or to run it at the application start. More details are available in the <a href="https://superface.ai/docs/upgrade/one-sdk-v2">upgrade guide</a>.</p><h3>Clean up of superface/ directory</h3><p>With the use of super.json configuration becoming optional, and the removal of local .supr files, we took the first steps towards phasing out the superface/ directory.</p><ul><li>The cache directory location changed from superface/.cache to node_modules/.cache/superface. superface/.cache directory can be removed.</li><li>superface/grid directory can be removed.</li></ul><p>You can find more details in the <a href="https://superface.ai/docs/upgrade/one-sdk-v2">upgrade guide</a>.</p><h3>Tell us your feedback</h3><p>We are eager to hear your feedback about our latest release. Join us on the <a href="https://sfc.is/discord">Superface Discord server</a> to tell us what you are building, or hit us up on <a href="https://twitter.com/superfaceai">Twitter</a>. If you run into any issues, report them in the <a href="https://github.com/superfaceai/one-sdk-js">OneSDK repository</a>. Or just <a href="https://superface.ai/docs/support">reach out to us</a> — we are happy to help!</p><p><em>Originally published at </em><a href="https://superface.ai/blog/one-sdk-2.0"><em>https://superface.ai</em></a><em> on August 16, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=dc0574b527c7" width="1" height="1" alt=""><hr><p><a href="https://medium.com/superface/look-ma-no-config-file-introducing-onesdk-2-0-dc0574b527c7">‘Look ma, no config file!’ Introducing OneSDK 2.0</a> was originally published in <a href="https://medium.com/superface">Superface</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Automate npm publishing with GitHub Actions, proper changelog, and release notes]]></title>
            <link>https://medium.com/superface/automate-npm-publishing-with-github-actions-proper-changelog-and-release-notes-a43839d0c3f6?source=rss----a27729ffd476---4</link>
            <guid isPermaLink="false">https://medium.com/p/a43839d0c3f6</guid>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[changelog]]></category>
            <category><![CDATA[npm-publish]]></category>
            <category><![CDATA[github-actions]]></category>
            <category><![CDATA[release-management]]></category>
            <dc:creator><![CDATA[Jan Halama]]></dc:creator>
            <pubDate>Thu, 23 Jun 2022 07:06:10 GMT</pubDate>
            <atom:updated>2022-06-23T07:06:10.295Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*pZLXMN-f9Dm9wF7x.jpg" /></figure><p>If you maintain at least one Node.js package, you probably know how painful the releases can be. Maybe running npm publish works for you just fine, but there are so many little details one can forget: running tests with clean dependencies, keeping the changelog up to date, creating release notes... Maintaining high quality of releases is difficult, especially in a team. Usually, it makes sense to automate the release process.</p><p>At Superface, we use GitHub Actions to automate the release workflow for npm packages. When we designed the process, we had the following requirements:</p><ul><li>Start the release manually with an appropriate <a href="https://docs.npmjs.com/cli/v8/commands/npm-version">version bump</a> (patch, minor, major, prepatch, preminor, premajor, or prerelease)</li><li>Support for manually maintained changelog file (using <a href="https://keepachangelog.com/">Keep a Changelog</a> conventions)</li><li>Automatically tag the package version in the repository and publish release notes with <a href="https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository">GitHub Release</a></li><li>Publish the package to npm registry with appropriate <a href="https://docs.npmjs.com/cli/v8/commands/npm-dist-tag">distribution tags</a> (latest for stable versions, next or beta for pre-release versions with)</li><li>Automatically publish prerelease versions on certain branches for beta testing</li></ul><p>Since new releases cause churn for package users, we want to be certain our release notes are usable. That’s why we prefer a handcrafted changelog following the <a href="https://keepachangelog.com/">Keep a Changelog</a> convention over automatic release notes generated from commit messages.</p><p>Unlike <a href="https://www.conventionalcommits.org/">Conventional Commits</a> and <a href="https://github.com/semantic-release/semantic-release">semantic-release</a>, we let the developer choose the release type ( major, minor, patch) and the time at which the package is released.</p><p>The following steps will guide you through the setup of automated npm package releasing:</p><ol><li><a href="https://superface.ai/blog/npm-publish-gh-actions-changelog#generate-a-new-npm-access-token">Generate a new npm access token</a></li><li><a href="https://superface.ai/blog/npm-publish-gh-actions-changelog#save-npm-access-token-as-a-github-secret">Save npm access token as a GitHub secret</a></li><li><a href="https://superface.ai/blog/npm-publish-gh-actions-changelog#add-github-workflow-to-your-repository">Add GitHub Workflow to your repository</a></li><li><a href="https://superface.ai/blog/npm-publish-gh-actions-changelog#release-the-npm-package">Release the npm package</a></li></ol><h3>Generate a new npm access token</h3><p>First we need an access token for npm registry in order to publish package with GitHub Actions. <a href="https://docs.npmjs.com/creating-and-viewing-access-tokens">Create a new access token</a> at npmjs.com for Automation and copy it for the next step.</p><figure><img alt="New access token page with Automation type selected." src="https://cdn-images-1.medium.com/max/1024/1*k0vwXK1SYcj5x0t4OJ1y7A.png" /></figure><h3>Save npm access token as a GitHub secret</h3><p>We will store the generated token for GitHub Actions as a <a href="https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository">repository secret</a>. In your GitHub repository settings, visit “Secrets” → “Actions”, click “New repository secret”, and add the npm access token created in the previous step. We will name the secret NPMJS_ACCESS_TOKEN.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QALcUM-oJEMN5SNc23D9ng.png" /></figure><h3>Add GitHub workflow to your repository</h3><p>In your project, create a new GitHub workflow file called release_package.yml, in the .github/workflows directory. Paste the following code. Optionally, you can change user.email and user.name under &quot;Git configuration&quot; step and uncomment the &quot;Run tests&quot; step along with the &quot;Install dependencies&quot; step.</p><p>Finally, commit the file and push the changes to your main branch.</p><pre>name: Release package<br>on:<br>  workflow_dispatch:<br>    inputs:<br>      release-type:<br>        description: &#39;Release type (one of): patch, minor, major, prepatch, preminor, premajor, prerelease&#39;<br>        required: true<br>jobs:<br>  release:<br>    runs-on: ubuntu-latest<br>    steps:<br>      # Checkout project repository<br>      - name: Checkout<br>        uses: actions/checkout@v2.3.4<br><br>      # Setup Node.js environment<br>      - name: Setup Node.js<br>        uses: actions/setup-node@v2<br>        with:<br>          registry-url: https://registry.npmjs.org/<br>          node-version: &#39;14&#39;<br><br>      # Install dependencies (required by Run tests step)<br>      #- name: Install dependencies<br>      #  run: yarn install<br><br>      # Tests<br>      #- name: Run tests<br>      #  run: yarn test<br><br>      # Configure Git<br>      - name: Git configuration<br>        run: |<br>          git config --global user.email &quot;41898282+github-actions[bot]@users.noreply.github.com&quot;<br>          git config --global user.name &quot;GitHub Actions&quot;<br><br>      # Bump package version<br>      # Use tag latest<br>      - name: Bump release version<br>        if: startsWith(github.event.inputs.release-type, &#39;pre&#39;) != true<br>        run: |<br>          echo &quot;NEW_VERSION=$(npm --no-git-tag-version version $RELEASE_TYPE)&quot; &gt;&gt; $GITHUB_ENV<br>          echo &quot;RELEASE_TAG=latest&quot; &gt;&gt; $GITHUB_ENV<br>        env:<br>          RELEASE_TYPE: ${{ github.event.inputs.release-type }}<br><br>      # Bump package pre-release version<br>      # Use tag beta for pre-release versions<br>      - name: Bump pre-release version<br>        if: startsWith(github.event.inputs.release-type, &#39;pre&#39;)<br>        run: |<br>          echo &quot;NEW_VERSION=$(npm --no-git-tag-version --preid=beta version $RELEASE_TYPE<br>          echo &quot;RELEASE_TAG=beta&quot; &gt;&gt; $GITHUB_ENV<br>        env:<br>          RELEASE_TYPE: ${{ github.event.inputs.release-type }}<br><br>      # Update changelog unreleased section with new version<br>      - name: Update changelog<br>        uses: superfaceai/release-changelog-action@v1<br>        with:<br>          path-to-changelog: CHANGELOG.md<br>          version: ${{ env.NEW_VERSION }}<br>          operation: release<br><br>      # Commit changes<br>      - name: Commit CHANGELOG.md and package.json changes and create tag<br>        run: |<br>          git add &quot;package.json&quot;<br>          git add &quot;CHANGELOG.md&quot;<br>          git commit -m &quot;chore: release ${{ env.NEW_VERSION }}&quot;<br>          git tag ${{ env.NEW_VERSION }}<br><br>      # Publish version to public repository<br>      - name: Publish<br>        run: yarn publish --verbose --access public --tag ${{ env.RELEASE_TAG }}<br>        env:<br>          NODE_AUTH_TOKEN: ${{ secrets.NPMJS_ACCESS_TOKEN }}<br><br>      # Push repository changes<br>      - name: Push changes to repository<br>        env:<br>          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}<br>        run: |<br>          git push origin &amp;&amp; git push --tags<br><br>      # Read version changelog<br>      - id: get-changelog<br>        name: Get version changelog<br>        uses: superfaceai/release-changelog-action@v1<br>        with:<br>          path-to-changelog: CHANGELOG.md<br>          version: ${{ env.NEW_VERSION }}<br>          operation: read<br><br>      # Update GitHub release with changelog<br>      - name: Update GitHub release documentation<br>        uses: softprops/action-gh-release@v1<br>        with:<br>          tag_name: ${{ env.NEW_VERSION }}<br>          body: ${{ steps.get-changelog.outputs.changelog }}<br>          prerelease: ${{ startsWith(github.event.inputs.release-type, &#39;pre&#39;) }}<br>        env:<br>          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}</pre><h3>Release the npm package</h3><h4>Update the changelog</h4><p>Before you proceed to trigger a new release, add notable changes to the changelog file. Our workflow requires that you stick with the <a href="https://keepachangelog.com/">Keep a Changelog</a> convention.</p><p>You can start with this empty CHANGELOG.md file:</p><pre># Changelog<br><br>All notable changes to this project will be documented in this file.<br><br>The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),<br>and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).<br><br>## [Unreleased]<br><br>### Added<br><br>- Changelog</pre><p>As you commit changes to your project, write them down into the [Unreleased] section. Once you trigger a new release, unreleased changes are automatically moved under the new version heading.</p><h4>Trigger new release</h4><p>You can find the “Run workflow” button in your GitHub repository under “Actions” → “Release package”.</p><figure><img alt="Screenshot GitHub Actions run workflow." src="https://cdn-images-1.medium.com/max/1024/1*M9bGU9sTF8Qx869vvOHCcQ.png" /></figure><p>Our <a href="https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch">worfklow_dispatch</a> event takes a single parameter named release type ( major, minor, patch, ...). The parameter is passed to the <a href="https://docs.npmjs.com/cli/v8/commands/npm-version">npm version command</a> in order to bump version of the package.</p><p>Once you press the “Run workflow” button, all the magic will happen, and your npm package will be released.</p><h3>Conclusion</h3><p>Our workflow automates the boring parts, while keeping us in control regarding when and how to release new packages’ versions. Support for the Keep a Changelog convention and GitHub Releases help us communicate changes to developers.</p><p>You can see the workflow in action in most of our package repositories, for example <a href="https://github.com/superfaceai/one-sdk-js">OneSDK for Node.js</a> and <a href="https://github.com/superfaceai/cli">Superface CLI</a>.</p><p>We are curious about how you manage your releases. Is your process fully automated, or do you just run npm publish locally? Do you maintain a changelog manually or generate it from commit messages? Let us know in the comments or join us on <a href="https://sfc.is/discord">Discord</a>!</p><p><em>Originally published at </em><a href="https://superface.ai/blog/npm-publish-gh-actions-changelog"><em>https://superface.ai</em></a><em> on June 21, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a43839d0c3f6" width="1" height="1" alt=""><hr><p><a href="https://medium.com/superface/automate-npm-publishing-with-github-actions-proper-changelog-and-release-notes-a43839d0c3f6">Automate npm publishing with GitHub Actions, proper changelog, and release notes</a> was originally published in <a href="https://medium.com/superface">Superface</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Less integrating, more community building: saving €40k on API integrations]]></title>
            <link>https://medium.com/superface/less-integrating-more-community-building-saving-40k-on-api-integrations-e78bbb1c8a50?source=rss----a27729ffd476---4</link>
            <guid isPermaLink="false">https://medium.com/p/e78bbb1c8a50</guid>
            <category><![CDATA[development]]></category>
            <category><![CDATA[integration]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[case-study]]></category>
            <category><![CDATA[api-integration]]></category>
            <dc:creator><![CDATA[Radek Novotny]]></dc:creator>
            <pubDate>Wed, 01 Jun 2022 13:54:32 GMT</pubDate>
            <atom:updated>2022-06-01T13:54:32.581Z</atom:updated>
            <content:encoded><![CDATA[<p>Crowd.dev is an early-stage startup with a unique community building and management product for developer-first companies. Their growth and business model are dependent on a large number of integrations. Instead of spending valuable time of their backend dev team, CTO Joan chose to handle integrations with Superface.</p><p>We met with <a href="https://crowd.dev/">crowd.dev</a> at Web Summit Lisbon 2021, where founders <a href="https://www.linkedin.com/in/jonathimer/">Jonathan Reimer</a> (CEO) and <a href="https://www.linkedin.com/in/joan-reyero-585171198/">Joan Reyero</a> (CTO) presented their vision of how crowd.dev could help manage developer communities. They are building a community management, growth, and engagement tool, by aggregating and acting on data from platforms where the community meets and interacts.</p><p>Crowd.dev’s founders are experts in this field, and have brought their expertise to the web service they offer for community-led companies.</p><figure><img alt="Diagram showing crowd.dev centralizing various data sources, like GitHub, Twitter, Reddit, or Discord, into solutions: Generate leads, drive community adoption, engage members, discover advocates, and reduce support effort" src="https://cdn-images-1.medium.com/max/1024/1*nGjQsQ75mL_ik8m_kxRWQg.png" /><figcaption>source: <a href="https://crowd.dev/">crowd.dev</a></figcaption></figure><h3>Dependency on data</h3><p>Crowd.dev’s success relies on the amount of external data they are able to get from third parties. Their business is critically dependent on the amount of integrations. Even expert founders like Jonathan and Joan don’t have many options today to handle integrations without having to hire backend developers.</p><p>Integration platforms (iPaaS) won’t help them, because crowd.dev’s business requires a large amount of API calls which gets prohibitively expensive, as those platforms’ business models are based on the volume of usage.</p><p>Initially, Jonathan and Joan were considering the time-consuming and expensive processes of acquiring more development power in order to build integrations from scratch.</p><h3>Cost and time per integration</h3><p>Joan (CTO &amp; founder) outlined a roadmap of required integrations that included categories such as: Social Media, Community Portals, Messaging Platforms, Development Tools and CRMs. Each category had at least 5 major players, each with different APIs.</p><p>All API integrations need to be prepared and tested thoroughly, as they are critical to crowd.dev business and its scaling. On average, the development of a single bespoke API integration takes 2–4 weeks, and the initial price can easily reach €1500. The price is even higher for mature companies.</p><p>In sum, Joan has to budget a minimum of €37,500 and 7 months of development, and that is a painful prospect. Not to mention, these figures do not include the expense of hiring a new backend developer, nor the long-term maintenance of these integrations.</p><figure><img alt="Table of Programming of API integration costs and time effort in 2022. Developer cost (Europe): €6,000 / month; Time to develop one API integration: 1–2 weeks of development; Cost of one API integration (medium complex API like Twitter): €1,500–€3,000; Maintenance of one API integration: €1,000 / year." src="https://cdn-images-1.medium.com/max/1024/1*ppJVvnotakr1z9jgM8YuTQ.png" /><figcaption>Calculating how much an API integration costs today</figcaption></figure><p>Simply put, integrations are expensive, don’t scale, but at the same time, are essential to running crowd.dev’s business.</p><h3>Fewer developers and more integrations</h3><p>We provided Joan with a number of ready-to-use integrations in the form of Superface use cases, which give applications the <a href="https://superface.ai/blog/self-integrating-applications">capability to integrate autonomously</a>. They were developed in Comlink, an open-source language we created specifically to make API integrations easier, faster, and more scalable.</p><p>However, Superface didn’t support Twitter nor Discord at that time. Our Customer Success team has therefore developed these integrations and published them in the public catalog, meaning other companies can use them for free as well. It should be noted that both Discord and Twitter have a complex API, which most developers struggle to properly integrate. Thanks to the technology we have developed, it took a fraction of the effort and cost compared to the conventional method.</p><blockquote>Thanks to Superface, the team can focus on building features rather than integrations, and we do not need to hire a developer just for talking to APIs.</blockquote><blockquote>— Joan Reyero, CTO, crowd.dev</blockquote><figure><img alt="Table of Benefits of using Superface with cost and time savings. Saved Developer cost (Europe): €72,000 / year; Time to integrate (ready-made integration use case): few minutes; Time to develop new integration use case: 4–8 hours; Cost of developing new integration use case: €150–€300." src="https://cdn-images-1.medium.com/max/1024/1*nPvTl13A1C-28AKaQfTrXA.png" /><figcaption>Calculating how much an API integration costs with Superface.</figcaption></figure><p>Crowd.dev started using Superface in a test environment, and in production shortly after. Within minutes, they had Superface and relevant integration use cases installed and configured. As of now, Superface records more than 100,000 successful Comlink executions per day.</p><figure><img alt="Chart showing number of Superface use cases executed by crowd.dev per week" src="https://cdn-images-1.medium.com/max/1024/1*zaaFbr5jvXdPeNwBnMf1mg.png" /><figcaption>Report shows crowd.dev using Superface for 100K+ executions daily</figcaption></figure><p>Crowd.dev themselves developed an integration for Slack, and contributed it to the Superface catalog.</p><blockquote>[Integrating] Slack was a breeze because we already had Discord, and Comlink is extremely easy to use.</blockquote><blockquote>— Joan Reyero, CTO, crowd.dev</blockquote><h3>Superface 💙 crowd.dev</h3><p>Crowd.dev is developing a product worth checking out. It’s currently in a closed beta version for registered users only — you can <a href="https://www.crowd.dev/#waitlist">sign up for crowd.dev waitlist</a>.</p><p>The professional approach and expert knowledge of its founders Jonathan and Joan make it a unique solution, whose integrations can now scale without limit, thanks to Superface.</p><p><em>Originally published at </em><a href="https://superface.ai/blog/case-study-crowd-dev"><em>https://superface.ai</em></a><em> on May 27, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e78bbb1c8a50" width="1" height="1" alt=""><hr><p><a href="https://medium.com/superface/less-integrating-more-community-building-saving-40k-on-api-integrations-e78bbb1c8a50">Less integrating, more community building: saving €40k on API integrations</a> was originally published in <a href="https://medium.com/superface">Superface</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Lessons learned integrating AppSignal APM with NestJS]]></title>
            <link>https://medium.com/superface/lessons-learned-integrating-appsignal-apm-with-nestjs-d0ebf391949c?source=rss----a27729ffd476---4</link>
            <guid isPermaLink="false">https://medium.com/p/d0ebf391949c</guid>
            <category><![CDATA[apm]]></category>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[signal-app]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[nestjs]]></category>
            <dc:creator><![CDATA[Jan Halama]]></dc:creator>
            <pubDate>Fri, 20 May 2022 14:13:01 GMT</pubDate>
            <atom:updated>2022-05-26T08:45:54.934Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*yvE2Zi_p26a7E_QU.jpg" /></figure><p>At Superface, we use NestJS framework for backend, and AppSignal APM for monitoring and error tracking. While AppSignal provides a Node.js integration, getting it up and running with NestJS proved to be somewhat tricky.</p><p>In this blog post, I will share how we managed to get AppSignal to work with NestJS.</p><p>Code snippets used in this blog post are part of our <a href="https://github.com/superfaceai/nestjs-appsignal-example">example project</a>.</p><h3>AppSignal initialization and configuration</h3><p>AppSignal uses auto-instrumentation which attaches hooks into Node.js tools and frameworks (Express, Koa, PostgreSQL, Redis, …) and observes for certain functions to be called. Once the functions are called, the instrumentation automatically collects trace spans on behalf of your application.</p><p>AppSignal has the following requirements (taken from AppSignal <a href="https://docs.appsignal.com/nodejs/installation.html">docs</a>) to make auto-instrumentation work:</p><blockquote><em>To auto-instrument modules, the </em><em>Appsignal module must be both </em><strong><em>required</em></strong><em> and </em><strong><em>initialized</em></strong><em> before any other package.</em></blockquote><p>The standard way to instantiate objects in NestJS is using the Dependency Injection (DI) Container.</p><p>To fulfill the requirement, we cannot use NestJS DI Container to instantiate AppSignal. AppSignal has to be instantiated as a global variable, which also means that we cannot take advantage of NestJS ConfigModule.</p><p>Example of AppSignal instantiation and configuration using environment variables:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/b64aa45b1602427f694bb11697138547/href">https://medium.com/media/b64aa45b1602427f694bb11697138547/href</a></iframe><p>You also need to register the AppSignal middleware when initializing Express in NestJS application bootstrap code:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/f1c21efaf1165fe8394c4968a735f56e/href">https://medium.com/media/f1c21efaf1165fe8394c4968a735f56e/href</a></iframe><p>That’s it, once you set APPSIGNAL_PUSH_API_KEY environment variable to valid AppSignal key and configure APPSIGNAL_NAME, APPSIGNAL_ACTIVE environment variables, AppSignal will start collecting metrics from all HTTP requests handled by your application.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gOVIQvMcb8bmwf_kUcvFSQ.jpeg" /><figcaption>AppSignal Dashboard</figcaption></figure><h3>Error tracking</h3><p>Nest comes with a built-in exceptions layer, which is responsible for processing all unhandled exceptions across an application. See Nest <a href="https://docs.nestjs.com/exception-filters">Exception filters docs</a> for details.</p><p>To track errors handled by Nest exception filters, we have created AppsignalExceptionFilter which implements Nest ExceptionFilter interface.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3a7df9e40eaa1dbaf213b83c68b3c6ef/href">https://medium.com/media/3a7df9e40eaa1dbaf213b83c68b3c6ef/href</a></iframe><p>The AppsignalExceptionFilter tracks HttpException exceptions with status code 5xx and any other exception types.</p><p>You can use AppsignalExceptionFilter by extending it in your custom exception filter implementation and register your exception filter in Nest app.</p><p>Example of extending AppsignalExceptionFilter:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3f3ede1a323eb3b43ebf57c9ded66439/href">https://medium.com/media/3f3ede1a323eb3b43ebf57c9ded66439/href</a></iframe><p>Example of global filter registration:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/f32b809174516811d0d9a1300643b479/href">https://medium.com/media/f32b809174516811d0d9a1300643b479/href</a></iframe><h3>Monitoring @nestjs/bull processes</h3><p>In addition to NestJS we also use <a href="https://github.com/OptimalBits/bull">Bull</a> for background jobs processing. NestJS provides @nestjs/bull package as a wrapper of for Bull.</p><p>AppSignal doesn’t trace Bull jobs automatically. Fortunately, we can use <a href="https://docs.appsignal.com/nodejs/instrumentation/">Appsignal custom instrumentation</a> to handle tracing ourselves.</p><p>To trace Bull jobs, we have created a Bull process decorator ProcessMonitor:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/823778a212044ffcff545857e4731fe2/href">https://medium.com/media/823778a212044ffcff545857e4731fe2/href</a></iframe><p>The ProcessMonitor method decorator creates new span in worker namespace, collects job ID, sets span with the error in case an exception occurs.</p><p>Once you add ProcessMonitor decorator into your code base, start using it by decorating your Bull queue processor method:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/d20f764df9c3d1d26c8fce0bfbf68a7f/href">https://medium.com/media/d20f764df9c3d1d26c8fce0bfbf68a7f/href</a></iframe><h3>Graceful AppSignal stopping</h3><p>By default, @appsignal/nodejs starts <a href="https://docs.appsignal.com/nodejs/instrumentation/minutely-probes.html">minutely probes</a>, which keep track of Node.js V8 heap statistics. This feature gives you insights about Node.js internals.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ymZ2QT_njQVy5YwnhFmtlg.jpeg" /><figcaption>Node.js V8 heap statistics in AppSignal Dashboard</figcaption></figure><p>Unfortunately, with minutely probes enabled, you have to explicitly stop the probes by calling the stop method. Otherwise your application process won&#39;t stop gracefully.</p><p>Nest comes with the onApplicationShutdown <a href="https://docs.nestjs.com/fundamentals/lifecycle-events#lifecycle-events-1">lifecycle event</a>, which is the right place to call AppSignal stop method. See example of AppsignalShutdownService implementation below:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/071f5ea43b929c3f7c501fcad507f883/href">https://medium.com/media/071f5ea43b929c3f7c501fcad507f883/href</a></iframe><p>Do not forget to add AppsignalShutdownService in your Nest application module.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/e5c19d2dd4e2c66ee88af02504dd0c18/href">https://medium.com/media/e5c19d2dd4e2c66ee88af02504dd0c18/href</a></iframe><p><em>Originally published at </em><a href="https://superface.ai/blog/nestjs-with-appsignal"><em>https://superface.ai</em></a><em> on May 20, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d0ebf391949c" width="1" height="1" alt=""><hr><p><a href="https://medium.com/superface/lessons-learned-integrating-appsignal-apm-with-nestjs-d0ebf391949c">Lessons learned integrating AppSignal APM with NestJS</a> was originally published in <a href="https://medium.com/superface">Superface</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[From OpenAPI to a working integration in minutes]]></title>
            <link>https://medium.com/superface/from-openapi-to-a-working-integration-in-minutes-5568f70d20a1?source=rss----a27729ffd476---4</link>
            <guid isPermaLink="false">https://medium.com/p/5568f70d20a1</guid>
            <category><![CDATA[code-generation]]></category>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[api-integration]]></category>
            <category><![CDATA[openapi-specification]]></category>
            <dc:creator><![CDATA[Jan Vlnas]]></dc:creator>
            <pubDate>Wed, 18 May 2022 11:03:32 GMT</pubDate>
            <atom:updated>2022-05-18T11:03:30.724Z</atom:updated>
            <cc:license>http://creativecommons.org/licenses/by/4.0/</cc:license>
            <content:encoded><![CDATA[<h4>Use <a href="https://superface.ai/designer">Integration designer</a> to create an API integration from OpenAPI document immediately usable in your application with <a href="https://github.com/superfaceai/one-sdk-js">OneSDK</a>. Publish the integration to the public registry and download a generated starter project.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*leRDtICNz5bWmuLQ" /><figcaption>Photo by <a href="https://unsplash.com/es/@agk42?utm_source=medium&amp;utm_medium=referral">Alex Knight</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>You are supposed to integrate a new service via API. Hopefully, that API has some documentation. Even better, that API has a specification, like OpenAPI Description. What is your next step? Will you painfully write the integration code manually? Or let the computer automate the boring parts for you?</p><p>Dealing with API integrations isn’t fun, which is why we are building Superface in the first place. While you can install a <a href="https://superface.ai/catalog">ready-made integration from the catalog</a>, writing a custom integration used to be a manual process.</p><p>Now there is another option: generate the integration using the Integration designer. This tool takes an OpenAPI Description document for your API and creates an integration for a single API endpoint. You can immediately try the generated integration from your browser, publish it to the public registry, and download a starter project.</p><h3>How it works</h3><p>The designer normalizes the OpenAPI Description with Stoplight’s <a href="https://github.com/stoplightio/http-spec">HTTP Spec library</a>. This library also handles Swagger documents and Postman collections, which we may support in the future.</p><p>Once you pick an endpoint, the designer splits the integration into three parts:</p><ul><li><strong>Profile</strong>, an interface definition which describes the structure of input and output data,</li><li><strong>Map</strong>, which describes the integration logic — which endpoints to use, how to format the data and how to pass the output,</li><li><strong>Provider definition</strong>, specifying a base server URL and security schemas used by the API.</li></ul><p>Once generated and properly named, the integration is ready for consuming by <a href="https://github.com/superfaceai/one-sdk-js">OneSDK</a>. The in-browser demo executes the integration with a serverless function using a simplified version of OneSDK.</p><h3>What makes it different</h3><p>There are a <a href="https://openapi.tools/#sdk">handful of tools</a> for generating SDK from OpenAPI Description, so what makes the Superface integration designer better?</p><ul><li><strong>Maintenance:</strong> Superface integrations strictly decouple the interface definition (profile) from the integration logic (map). With this approach, you can maintain the logic independently and, if needed, swap the providers without affecting your application’s code.</li><li><strong>Reusability:</strong> If you decide to publish the integration into the public registry, you can install it into multiple projects without dealing with packaging.</li><li><strong>Evolution:</strong> Additionally, you can update the published map in the registry. Applications using OneSDK can fetch the updated map in the runtime without need for redeploy.</li></ul><p>Other benefits of Superface apply as well. Since OneSDK performs the integration logic locally, as part of your application, you are not limited by the number of executions. You can use Superface integrations with private APIs inside the company’s VPN. And there is no middleman or proxy server between your application and the API: your data never touches Superface servers.</p><h3>Try it yourself</h3><p><a href="https://superface.ai/designer"><strong>Try the integration designer</strong></a> with your OpenAPI documents. If you don’t have any document handy, we prepared a few examples for you, or you can find more OpenAPI documents on <a href="https://apis.guru/">APIs.guru</a>.</p><p>This is the first public version of the designer. Some things may not work properly yet — which is why we are looking for your feedback! You can report issues directly from the designer. Alternatively, you can hit us on <a href="https://sfc.is/discord">Discord</a> or <a href="https://superface.ai/support">contact us privately</a>.</p><p><em>Originally published at </em><a href="https://superface.ai/blog/integration-designer-announcement"><em>https://superface.ai</em></a><em> on May 17, 2022.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5568f70d20a1" width="1" height="1" alt=""><hr><p><a href="https://medium.com/superface/from-openapi-to-a-working-integration-in-minutes-5568f70d20a1">From OpenAPI to a working integration in minutes</a> was originally published in <a href="https://medium.com/superface">Superface</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>